Skip to main content

Installing and Configuring Jenkins

1. Installing on Linux

Install Jenkins on Linux using the package manager or direct download.

Method Command/Steps Notes
Using APT (Debian/Ubuntu)
curl -fsSL https://pkg.jenkins.io/debian-stable/jenkins.io.key | sudo apt-key add -
sudo sh -c 'echo deb https://pkg.jenkins.io/debian-stable binary/ > /etc/apt/sources.list.d/jenkins.list'
sudo apt update
sudo apt install jenkins
Ensure Java 11 or higher is installed.
Using YUM (RHEL/CentOS)
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.key
sudo yum install jenkins
Requires root access and Java 11 or higher.
Manual Download
wget https://get.jenkins.io/war/2.479/jenkins.war
java -jar jenkins.war --httpPort=8080
For testing or custom setups. Not recommended for production.

Example: Start Jenkins Service

sudo systemctl start jenkins
sudo systemctl enable jenkins
Note: Jenkins runs on port 8080 by default. Ensure the firewall allows traffic on this port.

2. Installing on Windows

Step Description Details
1 Download Jenkins Visit https://www.jenkins.io/download/ and download the Windows installer (.msi file).
2 Run the Installer Double-click the downloaded .msi file and follow the setup wizard. Choose installation directory (e.g., C:\Program Files\Jenkins).
3 Start Jenkins Service Jenkins will be installed as a Windows service. It starts automatically after installation.
4 Access Jenkins UI Open a browser and navigate to http://localhost:8080. The initial setup wizard will appear.

Example: Initial Setup Wizard

1. Open browser to http://localhost:8080
2. Unlock Jenkins using the initial admin password found in:
   C:\Program Files\Jenkins\secrets\initialAdminPassword
3. Install suggested plugins or select custom plugins.
4. Create the first admin user.
5. Configure Jenkins URL (optional).
6. Start using Jenkins.
Note: Ensure Windows Firewall allows traffic on port 8080.
Warning: Jenkins requires Java 11 or higher to run. Verify java -version in command prompt.

3. Installing on macOS

Install Jenkins on macOS using Homebrew or direct download.

Example: Install via Homebrew

brew install jenkins

Example: Install via Direct Download

curl -O https://get.jenkins.io/war/2.479/jenkins.war
Installation Method Command/Process Notes
Homebrew brew install jenkins Installs Jenkins and its dependencies automatically
Direct Download Download .war file from Jenkins website Requires manual setup of Java and servlet container
Note: Ensure Java 17 or higher is installed before installing Jenkins.
Warning: macOS may require additional configuration for firewall and security settings.

4. Running as Docker Container

Running Jenkins in a Docker container is a popular approach for easy deployment and isolation.

Option Values Notes
docker run jenkins/jenkins:lts Latest LTS Jenkins image from Docker Hub
volume mapping -v jenkins_home:/var/jenkins_home Persists Jenkins configuration and data
port mapping -p 8080:8080 -p 50000:50000 Exposes Jenkins web UI and agent port

Example: Run Jenkins in Docker

docker run -d \
  --name jenkins \
  -p 8080:8080 \
  -p 50000:50000 \
  -v jenkins_home:/var/jenkins_home \
  jenkins/jenkins:lts
Note: The first time Jenkins starts, it will generate an initial admin password. You can retrieve this from the container logs or by running docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword.
Warning: Ensure that the volume mapping persists Jenkins data across container restarts or recreation.

Summary of Docker Deployment Steps

  • Create a Docker volume or bind mount for Jenkins home directory
  • Run the Jenkins LTS image with port and volume mappings
  • Access Jenkins via http://localhost:8080
  • Complete the initial setup wizard using the generated admin password

5. Installing on Kubernetes

Example: Deploy Jenkins to Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: jenkins-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: jenkins
  template:
    metadata:
      labels:
        app: jenkins
    spec:
      containers:
      - name: jenkins
        image: jenkins/jenkins:lts
        ports:
        - containerPort: 8080
        volumeMounts:
        - name: jenkins-home
          mountPath: /var/jenkins_home
      volumes:
      - name: jenkins-home
        persistentVolumeClaim:
          claimName: jenkins-pvc
---
apiVersion: v1
kind: Service
metadata:
  name: jenkins-service
spec:
  selector:
    app: jenkins
  ports:
    - protocol: TCP
      port: 80
      targetPort: 8080
  type: LoadBalancer
Component Description Notes
Deployment apps/v1 Manages the Jenkins pod lifecycle
Service v1 Exposes Jenkins to external traffic
PersistentVolumeClaim v1 Stores Jenkins configuration and data
Note: Ensure Kubernetes cluster has sufficient resources (CPU, memory) for Jenkins to run effectively.
Warning: Jenkins on Kubernetes requires proper RBAC configuration for secure access.

6. Configuring System Settings

Setting Description Default Value Notes
System Message Global system message displayed on Jenkins dashboard None Can include HTML formatting
Admin Email Address Email address of the Jenkins administrator Not set Used for notifications and alerts
Jenkins URL Public URL of the Jenkins instance Auto-detected Must be accessible from agents and users
Use Security Enable or disable security features Enabled Recommended to keep enabled for production
Authorization Strategy Method used to control access to Jenkins Matrix-based Options include Role-Based, Global Matrix, etc.

Example: Setting Jenkins URL

curl -X POST "http://localhost:8080/scriptConsole" \
  --data-urlencode "script=Jenkins.instance.setRootUrl("https://jenkins.example.com")"
Note: Ensure the Jenkins URL is correctly set to avoid issues with build triggers and webhooks.
Warning: Changing the Jenkins URL without proper configuration can break builds and notifications.

7. Setting Up Home Directory

Example: Configuring Jenkins Home Directory

export JENKINS_HOME=/opt/jenkins
Configuration Value Description
JENKINS_HOME /var/lib/jenkins Default Jenkins home directory
JENKINS_HOME /opt/jenkins Custom Jenkins home directory path
Note: Ensure the Jenkins user has read/write permissions to the specified directory.
Warning: Moving JENKINS_HOME after initial setup may cause plugin or job misconfigurations.

8. Configuring Java Options

Option Description Default Value Notes
JAVA_HOME Path to the Java installation directory System default Must point to a valid JDK installation
JENKINS_JAVA_OPTIONS Additional JVM arguments for Jenkins -Djava.awt.headless=true Can include memory settings, GC options, etc.

Example: Setting Java Memory Limits

JENKINS_JAVA_OPTIONS="-Xms512m -Xmx2g" java -jar jenkins.war
Note: Ensure the specified Java version is compatible with your Jenkins version.

9. Setting Up Reverse Proxy

Example: Nginx Configuration

server {
    listen 80;
    server_name jenkins.example.com;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
Directive Description Default Value
proxy_pass Specifies the address of the upstream server None
proxy_set_header Sets custom headers to be passed to the upstream server None
Note: Ensure that the Jenkins server is running and accessible at the specified port before setting up the reverse proxy.

10. Enabling HTTPS and SSL Certificates

Example: Configure Jenkins HTTPS with SSL

# Generate a self-signed certificate
openssl req -x509 -newkey rsa:4096 -keyout jenkins.key -out jenkins.crt -days 365 -nodes

# Copy certificates to Jenkins directory
sudo cp jenkins.key /etc/ssl/private/jenkins.key
sudo cp jenkins.crt /etc/ssl/certs/jenkins.crt

# Set proper permissions
sudo chmod 600 /etc/ssl/private/jenkins.key
sudo chmod 644 /etc/ssl/certs/jenkins.crt
Configuration Property Value Description
jenkins.model.Jenkins.HTTPS_PORT 8443 HTTPS port Jenkins listens on
jenkins.model.Jenkins.HTTPS_KEYSTORE /etc/ssl/certs/jenkins.jks Path to keystore file (JKS format)
jenkins.model.Jenkins.HTTPS_KEYSTORE_PASSWORD changeit Password for the keystore
Note: For production use, obtain a certificate from a trusted Certificate Authority (CA) rather than using self-signed certificates.
Warning: Ensure that the keystore file is properly secured and only accessible by the Jenkins process.

HTTPS Configuration Summary

  • Set HTTPS_PORT to enable HTTPS access
  • Use a valid keystore with private key and certificate
  • Secure the keystore file permissions
  • Update firewall rules to allow traffic on HTTPS port

11. Configuring Port and Context Path

Property Default Value Description
jenkins.port 8080 Port on which Jenkins listens for HTTP requests
jenkins.contextPath / Context path for Jenkins web application

Example: Setting Port and Context Path via CLI

java -jar jenkins.war --httpPort=9090 --contextPath=/jenkins

Example: Setting Port and Context Path via Environment Variables

JENKINS_PORT=9090
JENKINS_CONTEXT_PATH=/jenkins
Note: When using a custom context path, ensure that any reverse proxy or load balancer is configured to handle the new path correctly.

12. Setting Up Initial Admin Password

Example: Setting Up Initial Admin Password

sudo cat /var/lib/jenkins/secrets/initialAdminPassword
Step Description Command/Action
1 Locate the initial admin password file /var/lib/jenkins/secrets/initialAdminPassword
2 Retrieve the password using a command-line tool sudo cat /var/lib/jenkins/secrets/initialAdminPassword
3 Use the password to unlock Jenkins Enter the password in the Jenkins setup wizard
Note: The initial admin password is generated during Jenkins installation and is only accessible via the command line or file system.

Was this article helpful?