How to Install Jenkins on Linux, Windows, and macOS

1. What is Jenkins?

Jenkins is an open-source automation server that facilitates the automation of various stages in the software development lifecycle, including building, testing, and deploying applications. It is widely recognized as a leading tool for implementing Continuous Integration (CI) and Continuous Delivery (CD) pipelines.

Jenkins helps development teams to integrate code changes frequently, automatically test them, and rapidly deliver high-quality software, thereby reducing integration issues and accelerating the release process.

Key Benefits:

• Continuous Integration: Automates the merging and testing of code changes.
• Continuous Delivery/Deployment: Automates the release process to different environments.
• Extensibility: Offers over a thousand plugins for integration with virtually any tool or service.
• Open Source: Free to use and supported by a large, active community.
• Distributed Builds: Can distribute build workloads across multiple machines (agents).

2. Prerequisites (Java)

Jenkins is a Java-based application, so a compatible Java Development Kit (JDK) is required. As of recent Jenkins versions, **OpenJDK 11 or OpenJDK 17** are recommended.

A. Check for Java Installation:

Open your terminal or command prompt and run:

java -version

If Java is installed, you'll see version information. If not, or if it's an incompatible version (e.g., Java 8), you need to install or update it.

B. Install Java (OpenJDK 17 Recommended):

• Ubuntu/Debian:

  sudo apt update
  sudo apt install -y openjdk-17-jdk

• Red Hat/CentOS/Fedora:

  sudo dnf install -y java-17-openjdk-devel

• Windows:
  • Download the JDK installer (e.g., from Adoptium (Temurin) or Oracle).
  • Run the installer and follow the wizard.
  • Ensure `JAVA_HOME` environment variable is set and `%JAVA_HOME%\bin` is added to your system `Path`.
• macOS:
  • Use Homebrew: `brew install openjdk@17`
  • Or download installer from Adoptium.
  • Ensure `JAVA_HOME` is set in your shell profile (e.g., `~/.zshrc` or `~/.bash_profile`).

    # Example for macOS with Homebrew, add to ~/.zshrc or ~/.bash_profile
    export JAVA_HOME=$(/usr/libexec/java_home -v 17)
    export PATH=$JAVA_HOME/bin:$PATH
    # Then: source ~/.zshrc (or .bash_profile)

3. Installation Methods Overview

Jenkins can be installed in several ways. We'll cover direct OS installation and a popular containerized method.

• Operating System Specific Packages: (Recommended for production servers) Uses native package managers (APT for Debian/Ubuntu, DNF for Red Hat/CentOS/Fedora, Homebrew for macOS, MSI installer for Windows).
• Docker Container: (Recommended for quick setup, development, or testing) Runs Jenkins isolated within a Docker container.
• Generic Java WAR file: Can be run on any Servlet container (like Tomcat). More manual setup.

4. Install on Linux (Ubuntu/Debian)

This method uses the `apt` package manager for a system-wide installation.

A. Add Jenkins Repository Key:

sudo wget -O /usr/share/keyrings/jenkins-keyring.asc \
  https://pkg.jenkins.io/debian-stable/jenkins-keyring.asc

B. Add Jenkins Repository to Sources:

echo "deb [signed-by=/usr/share/keyrings/jenkins-keyring.asc] \
  https://pkg.jenkins.io/debian-stable binary/" | sudo tee \
  /etc/apt/sources.list.d/jenkins.list > /dev/null

C. Update Package Cache & Install Jenkins:

sudo apt update
sudo apt install -y jenkins

D. Start and Check Jenkins Service:

Jenkins should start automatically after installation.

sudo systemctl start jenkins
sudo systemctl status jenkins
# Expected output will show 'active (running)'

E. Adjust Firewall (if UFW is active):

sudo ufw allow 8080 # Jenkins default port
sudo ufw enable     # Enable firewall if it's not already
sudo ufw status     # Verify the rule is active

Jenkins will be accessible at `http://:8080`.

5. Install on Linux (Red Hat/CentOS/Fedora)

This method uses the `dnf` package manager (or `yum` for older CentOS/RHEL versions).

A. Add Jenkins Repository:

sudo wget -O /etc/yum.repos.d/jenkins.repo \
    https://pkg.jenkins.io/redhat-stable/jenkins.repo
sudo rpm --import https://pkg.jenkins.io/redhat-stable/jenkins.io-2023.key

B. Install Jenkins:

sudo dnf install -y jenkins # Use 'sudo yum install -y jenkins' for older systems

C. Start and Enable Jenkins Service:

sudo systemctl start jenkins
sudo systemctl enable jenkins
sudo systemctl status jenkins
# Expected output will show 'active (running)'

D. Adjust Firewall (if Firewalld is active):

sudo firewall-cmd --permanent --zone=public --add-port=8080/tcp # Allow HTTP access
sudo firewall-cmd --reload # Apply changes

Jenkins will be accessible at `http://:8080`.

6. Install on Windows

Jenkins provides a native Windows installer (MSI).

A. Download Jenkins MSI Installer:

Go to the official Jenkins website: jenkins.io/download/lts/windows/ and download the LTS installer.

B. Run the Installer:

1. Double-click the downloaded `.msi` file.
2. The Jenkins Setup Wizard will appear. Click **Next**.
3. Choose the **Destination Folder** for Jenkins (default is usually fine). Click **Next**.
4. Service Logon Type:
   • `Run service as LocalSystem (less secure)`: Easiest, but gives Jenkins broad system privileges.
   • `Run service as a local or domain user (recommended)`: More secure. You'll need to create a dedicated local Windows user (e.g., `jenkins`) and grant it necessary permissions (e.g., "Log on as a service" right in Local Security Policy). This is recommended for production.
   Choose the option that suits your needs for now (LocalSystem for quick testing). Click **Next**.
5. Port Selection: Default is `8080`. You can test it. If it conflicts, change it. Click **Test Port** to check availability. Click **Next**.
6. Java Home Directory: The installer should auto-detect your JDK. If not, click **Browse** and point it to your JDK 11/17 root directory (e.g., `C:\Program Files\Java\jdk-17`). Click **Next**.
7. Click **Install**.
8. Click **Finish**.

Jenkins should start automatically after installation. You can access it at `http://localhost:8080` (or your chosen port).

You can also manage the Jenkins service via `services.msc` (search in Windows Start Menu).

7. Install on macOS

The recommended way to install Jenkins on macOS is using Homebrew.

A. Install Homebrew (if not already installed):

Open Terminal.app (Finder > Applications > Utilities > Terminal) and run:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Follow the on-screen instructions to complete the Homebrew installation.

B. Install Jenkins via Homebrew:

brew install jenkins-lts

C. Start Jenkins Service:

# Start Jenkins (will launch automatically on login)
brew services start jenkins-lts

# Check status
brew services list # Look for jenkins-lts status

Jenkins will be accessible at `http://localhost:8080`.

Note: macOS Gatekeeper might initially block Jenkins. If prompted, go to System Settings > Privacy & Security > General and click "Open Anyway" for Jenkins.

8. Initial Jenkins Setup Wizard (All OS)

After Jenkins starts for the first time, you'll be redirected to a web-based setup wizard in your browser (at `http://:8080`).

A. Unlock Jenkins:

The first screen will ask for an administrator password. Retrieve it from your server's initial admin password file:

• Linux:

  sudo cat /var/lib/jenkins/secrets/initialAdminPassword

• Windows:

  type "C:\Program Files\Jenkins\secrets\initialAdminPassword"

• macOS (Homebrew):

  cat /Users/Shared/Jenkins/Home/secrets/initialAdminPassword

• Docker Container:

  docker logs <jenkins_container_id_or_name> # Look for the password in the logs

Paste the password into the browser field and click **Continue**.

B. Install Plugins:

• Choose **Install suggested plugins**. This is the easiest way to get started, installing common plugins for Git, Pipelines, build tools, etc.
• Alternatively, you can select specific plugins, but it's not recommended for a first-time setup.

Jenkins will proceed to download and install the selected plugins. This might take several minutes.

C. Create First Admin User:

Once plugins are installed, you'll be prompted to create your first administrator user. Fill in all the fields (Username, Password, Full Name, Email Address). **Remember these credentials!**

D. Instance Configuration:

Confirm your Jenkins URL. The default (`http://localhost:8080`) is usually fine for local setups. For servers, ensure it's your server's public IP or hostname. Click **Save and Finish**.

E. Jenkins Dashboard:

You'll now be redirected to the Jenkins dashboard. Your Jenkins instance is ready!

9. Post-Installation Steps

A. Install Recommended Tools:

Depending on your projects, you'll need build tools (Maven, Gradle, npm), SCM clients (Git), etc., on your Jenkins server or agents.

• Install Git:

  # Ubuntu/Debian
  sudo apt install -y git
  # Red Hat/CentOS/Fedora
  sudo dnf install -y git

• Configure Tools (GUI):

  Jenkins Dashboard > Manage Jenkins > Tools

  • **JDK Installations:** Add paths to other Java versions if needed.
  • **Maven Installations:** Add Maven versions.
  • **Gradle Installations:** Add Gradle versions.
  • **Git installations:** Add Git.

B. Explore Plugins:

Jenkins' power comes from its plugins. Explore the marketplace for plugins relevant to your workflow.

Jenkins Dashboard > Manage Jenkins > Plugins

C. Configure Security (Advanced):

For production environments, enhance security beyond the initial setup:

• Integrate with LDAP/Active Directory: For centralized user management.
• Enable HTTPS: Configure Jenkins behind a reverse proxy (Nginx, Apache) with SSL.
• Role-Based Access Control (RBAC): Use plugins like "Role-based Authorization Strategy" for fine-grained permissions.
• Set up Agents: For distributed builds, move workload off the controller.

10. Troubleshooting Common Issues

• Jenkins not starting / Port conflict:
  • Check if port 8080 (or your chosen port) is already in use by another application.
  • Check Jenkins service logs for errors:

    # Linux:
    sudo journalctl -u jenkins.service
    sudo cat /var/log/jenkins/jenkins.log
    # Windows:
    Check Event Viewer > Windows Logs > Application. Also check Jenkins installation folder for logs.

• Firewall blocking access:
  • Ensure port 8080 (and 50000 for agents) is open in your OS firewall. (See firewall commands in relevant OS sections).
  • If on a cloud VM, ensure the cloud provider's security groups/network ACLs allow traffic on these ports.
• Java issues:
  • Ensure a compatible Java JDK (11 or 17) is installed and configured correctly (especially `JAVA_HOME` and `PATH`).
  • Jenkins might default to an older Java if multiple are present.
• "Offline" agents/nodes:
  • Check network connectivity between controller and agent.
  • Verify Java installation on the agent.
  • Check SSH/JNLP connection settings in the agent configuration in Jenkins.
  • Look at the agent's launch log in Jenkins (Manage Jenkins > Nodes > Agent Name > Log).
• Plugin failures:
  • Go to **Manage Jenkins** > **Plugins** > **Installed plugins**. Look for plugins with errors or available updates.
  • Restart Jenkins after installing/updating plugins.
• Disk space issues:
  • Jenkins can consume a lot of disk space. Regularly clean up old build artifacts and workspaces.
  • Configure "Discard old builds" in job configurations.