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) | |
Ensure Java 11 or higher is installed. |
| Using YUM (RHEL/CentOS) | |
Requires root access and Java 11 or higher. |
| Manual Download | |
For testing or custom setups. Not recommended for production. |
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.
| 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
| 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. |
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_PORTto 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
| 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.