🚀 Production Installation Topography: Bare-Metal, Virtual Machine, or OCI Container
Deploying Jenkins for an enterprise CI/CD workload requires architectural planning before executing package managers. Choosing between a native Linux system package (systemd managed) and an OCI-compliant container (Docker/Kubernetes) dictates how storage persistence, OS updates, systemd service supervision, and backup strategies are handled. Jenkins requires a long-term support (LTS) Java Virtual Machine (OpenJDK 17 or 21), high-IOPS storage for disk-heavy workspace writes, dedicated UID/GID mapping for security sandboxing, and an external reverse proxy (Nginx or HAProxy) for TLS/SSL offloading. Below is the production engineering guide covering installation across major enterprise Linux distributions and container runtimes.
ENTERPRISE SIZING TIERS FOR JENKINS CONTROLLERS:
┌─────────────────┬─────────────┬─────────────┬────────────────────────┬───────────────────────────┐
│ DEPLOYMENT TIER │ CPU CORES │ SYSTEM RAM │ STORAGE IOPS & TYPE │ CONCURRENT JOBS/AGENTS │
├─────────────────┼─────────────┼─────────────┼────────────────────────┼───────────────────────────┤
│ Lab / Sandbox │ 2 vCPU │ 4 GB RAM │ 50 GB Standard SSD │ 1 - 5 Builds (10 Nodes) │
│ Departmental │ 4 - 8 vCPU │ 16 - 32 GB │ 250 GB NVMe (3000 IOPS)│ 20 - 50 Builds (50 Nodes) │
│ Enterprise Core │ 16 - 32 vCPU│ 64 - 128 GB │ 1 TB Provisioned IOPS │ 100+ Builds (500+ Nodes) │
└─────────────────┴─────────────┴─────────────┴────────────────────────┴───────────────────────────┘
JVM RUNTIME MATRIX (MODERN JENKINS CORE):
• Supported Java Versions: Java 17-bit / Java 21 LTS (Eclipse Temurin or OpenJDK recommended).
• Java 8 & 11: Completely deprecated and removed from modern Jenkins LTS releases.
• Storage Invariant: Solid-state storage (NVMe/SSD) is mandatory. The Controller writes
XML metadata and build console logs continuously; spinning HDDs cause catastrophic thread locks.
FIREWALL INGRESS RULES:
• Port 8080/TCP : Default web interface and REST API traffic (Forwarded via Reverse Proxy).
• Port 443/TCP : Secure HTTPS traffic terminating at reverse proxy (Nginx / Cloud Load Balancer).
• Port 50000/TCP: Inbound JNLP/TCP agent remoting listener (Optional if using modern WebSockets).
#!/usr/bin/env bash
# Production Jenkins LTS Installation Script for Debian/Ubuntu
set -euo pipefail
echo "[*] Step 1: Update package cache and install prerequisites..."
sudo apt-get update -y
sudo apt-get install -y curl gnupg fontconfig openjdk-17-jdk
echo "[*] Step 2: Verify OpenJDK 17 installation..."
java -version
echo "[*] Step 3: Import official Jenkins GPG binary key..."
# Modern Debian/Ubuntu key directory convention
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://pkg.jenkins.io/debian-stable/jenkins.io-2023.key | sudo tee \
/etc/apt/keyrings/jenkins-keyring.asc > /dev/null
echo "[*] Step 4: Register Jenkins LTS package repository..."
echo deb [signed-by=/etc/apt/keyrings/jenkins-keyring.asc] \
https://pkg.jenkins.io/debian-stable binary/ | sudo tee \
/etc/apt/sources.list.d/jenkins.list > /dev/null
echo "[*] Step 5: Update repository index and install Jenkins..."
sudo apt-get update -y
sudo apt-get install -y jenkins
echo "[*] Step 6: Enable and start systemd daemon..."
sudo systemctl daemon-reload
sudo systemctl enable jenkins
sudo systemctl start jenkins
echo "[*] Step 7: Check service operational status..."
sudo systemctl status jenkins --no-pager -l
#!/usr/bin/env bash
# Enterprise Jenkins LTS Installation for RHEL / Rocky / AlmaLinux
set -euo pipefail
echo "[*] Step 1: Install OpenJDK 17 LTS and networking tools..."
sudo dnf install -y java-17-openjdk java-17-openjdk-devel wget curl
echo "[*] Step 2: Download Jenkins Red Hat repository configuration..."
sudo wget -O /etc/yum.repos.d/jenkins.repo https://pkg.jenkins.io/redhat-stable/jenkins.repo
echo "[*] Step 3: Import official Jenkins RPM signing key..."
sudo rpm --import https://pkg.jenkins.io/redhat-stable/jenkins.io-2023.key
echo "[*] Step 4: Install Jenkins package via DNF..."
sudo dnf upgrade -y
sudo dnf install -y jenkins
echo "[*] Step 5: Configure Firewalld (if active)..."
if systemctl is-active --quiet firewalld; then
sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --permanent --add-port=50000/tcp
sudo firewall-cmd --reload
echo "[+] Firewalld rules updated successfully."
fi
echo "[*] Step 6: Start and enable Jenkins service..."
sudo systemctl daemon-reload
sudo systemctl enable --now jenkins
echo "[*] Step 7: Verify execution status..."
sudo systemctl status jenkins --no-pager
jenkins/jenkins:lts-jdk17) using Docker Compose. Enforcing correct volume permissions using host UID/GID 1000:1000 mapping.
version: '3.8'
services:
jenkins-controller:
image: jenkins/jenkins:lts-jdk17
container_name: jenkins-production
restart: unless-stopped
user: "1000:1000"
ports:
- "8080:8080"
- "50000:50000"
environment:
- JAVA_OPTS=-Duser.timezone=UTC -Xms4g -Xmx4g -XX:+UseG1GC -XX:+ExplicitGCInvokesConcurrent
- JENKINS_OPTS=--httpKeepAliveTimeout=30000
volumes:
- /opt/jenkins_data:/var/jenkins_home
networks:
- cicd-network
logging:
driver: "json-file"
options:
max-size: "50m"
max-file: "5"
deploy:
resources:
limits:
cpus: '4.0'
memory: 6G
reservations:
cpus: '2.0'
memory: 4G
networks:
cicd-network:
name: cicd-network
driver: bridge
# Prepare host persistence directory on Docker host
sudo mkdir -p /opt/jenkins_data
# The official jenkins image uses UID 1000 and GID 1000
sudo chown -R 1000:1000 /opt/jenkins_data
sudo chmod -R 775 /opt/jenkins_data
# Launch the container in detached daemon mode
docker compose up -d
# Verify container logs
docker compose logs -f jenkins-controller
systemctl edit jenkins. Tuning the Garbage First Collector (G1GC), heap allocation limits, and file descriptor limits (nofile).
# Execute via: sudo systemctl edit jenkins
# This safely overrides package defaults without being overwritten during apt/dnf updates.
[Service]
# Custom Environment Variables & Heap Configuration
Environment="JAVA_OPTS=-Djava.awt.headless=true \
-Duser.timezone=UTC \
-Xms8g -Xmx8g \
-XX:+UseG1GC \
-XX:+ExplicitGCInvokesConcurrent \
-XX:InitiatingHeapOccupancyPercent=45 \
-XX:G1ReservePercent=15 \
-XX:MinMetaspaceFreeRatio=50 \
-XX:MaxMetaspaceFreeRatio=80"
# Custom HTTP Port configuration
Environment="JENKINS_PORT=8080"
# Open File Descriptors (uLimit) Tuning for high concurrent agent traffic
LimitNOFILE=65536
LimitNPROC=32768
# Restart policies
Restart=on-failure
RestartSec=10
# Apply systemd overrides
sudo systemctl daemon-reload
sudo systemctl restart jenkins
# Inspect active JVM parameters on the running process
ps -ef | grep jenkins | grep -E "Xmx|G1GC"
# Verify that file descriptor limits were applied to the process
cat /proc/$(pgrep -f "jenkins.war")/limits | grep "Max open files"
upstream jenkins_backend {
server 127.0.0.1:8080 fail_timeout=0;
}
# Redirect HTTP to HTTPS
server {
listen 80;
server_name jenkins.company.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl http2;
server_name jenkins.company.com;
# SSL Certificates (managed via Certbot Let's Encrypt)
ssl_certificate /etc/letsencrypt/live/jenkins.company.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/jenkins.company.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
ssl_prefer_server_ciphers on;
# Pipeline Artifact Upload Size (Prevent HTTP 413 Payload Too Large)
client_max_body_size 500M;
client_body_buffer_size 128k;
location / {
proxy_pass http://jenkins_backend;
proxy_redirect default;
proxy_http_version 1.1;
# Mandatory Headers to resolve Jenkins "Reverse Proxy Broken" alerts
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;
proxy_set_header X-Forwarded-Port $server_port;
# WebSocket Support for modern agent connections and live log streaming
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
# Buffer & Timeout optimizations
proxy_connect_timeout 90;
proxy_send_timeout 90;
proxy_read_timeout 90;
proxy_buffering off; # Required for SSE and real-time console log streaming
proxy_request_buffering off;
}
}
# Case A: Bare-Metal / Native Linux systemd deployment
sudo cat /var/lib/jenkins/secrets/initialAdminPassword
# Case B: Docker containerized deployment
docker exec -it jenkins-production cat /var/jenkins_home/secrets/initialAdminPassword
# Output displays a 32-character hexadecimal key, for example:
# 4a8b7c9d0e1f2a3b4c5d6e7f8a9b0c1d
POST-BOOTSTRAP CONFIGURATION STEPS:
1. Unlock Jenkins:
• Navigate to http://server-ip:8080 (or https://jenkins.company.com).
• Paste the hexadecimal initialAdminPassword retrieved from the terminal.
2. Install Plugins:
• Select "Install suggested plugins" (Git, Pipeline, GitHub Branch Source, Matrix Authorization, Credentials).
• DO NOT install hundreds of plugins at bootstrap; install only verified plugins as needed.
3. Create First Admin User:
• Avoid using the default 'admin' username.
• Configure an explicit corporate administrator account with a strong passphrase.
4. Configure Jenkins URL:
• Navigate to: Manage Jenkins ➔ System.
• Set "Jenkins URL" explicitly to the public HTTPS domain (https://jenkins.company.com/).
• Incomplete configuration here causes broken email notification links and failed GitHub webhooks.
5. Enforce Controller-Agent Security:
• Navigate to: Manage Jenkins ➔ Security.
• Ensure "Agent to controller access control" is strictly ENABLED.
• Verify CSRF Protection is ACTIVE (Default in modern Jenkins).
FREQUENT FAILURE MODES & RESOLUTIONS:
1. PORT 8080 BINDING CONFLICT:
• Symptom: Jenkins fails to start; systemctl status reports 'Failed to start Jenkins Continuous Integration'.
• Diagnostic: sudo netstat -tulnp | grep 8080
• Cause: Another service (Tomcat, Apache, proxy) is already bound to port 8080.
• Remediation: Edit /etc/systemd/system/jenkins.service.d/override.conf and change
Environment="JENKINS_PORT=8081"
2. UNSUPPORTED JAVA VERSION:
• Symptom: journalctl -u jenkins reports:
'java.lang.UnsupportedClassVersionError: ... has been compiled by a more recent version of the Java Runtime'
• Cause: System default Java points to OpenJDK 11 or 8 instead of 17.
• Remediation:
sudo update-alternatives --config java
# Select the OpenJDK 17 option from the interactive terminal list.
3. GPG REPOSITORY KEY VALIDATION FAILED:
• Symptom: apt-get update reports:
'The following signatures couldn't be verified because the public key is not available: NO_PUBKEY ...'
• Cause: Jenkins updated their package repository signing key in 2023.
• Remediation: Re-import the modern 2023 key directly into /etc/apt/keyrings/:
curl -fsSL https://pkg.jenkins.io/debian-stable/jenkins.io-2023.key | sudo tee \
/etc/apt/keyrings/jenkins-keyring.asc > /dev/null
4. PERMISSION DENIED ON DOCKER SOCKET (DOCKER-IN-DOCKER AGENT BUG):
• Symptom: Pipeline fails with 'Got permission denied while trying to connect to the Docker daemon socket'.
• Remediation: If running builds via host Docker socket, add the jenkins user to the docker group:
sudo usermod -aG docker jenkins
sudo systemctl restart jenkins
JENKINS DEPLOYMENT SPECIFICATION MATRIX:
┌─────────────────────────┬──────────────────────────────┬──────────────────────────────────────┐
│ ATTRIBUTE / PATH │ NATIVE SYSTEMD (DEB/RPM) │ DOCKER CONTAINER (DOCKER COMPOSE) │
├─────────────────────────┼──────────────────────────────┼──────────────────────────────────────┤
│ Home Directory │ /var/lib/jenkins │ /var/jenkins_home (Mounted on Host) │
│ Configuration Files │ /var/lib/jenkins/config.xml │ /opt/jenkins_data/config.xml │
│ Systemd Service Unit │ /lib/systemd/system/jenkins │ /etc/systemd/system/docker.service │
│ Service Overrides │ /etc/systemd/system/... │ docker-compose.yml environment keys │
│ Web Application Archive │ /usr/share/java/jenkins.war │ /usr/share/jenkins/jenkins.war │
│ Log Files Location │ /var/log/jenkins/jenkins.log │ docker compose logs (json-file) │
│ Default User Account │ jenkins:jenkins (UID 1000) │ jenkins:jenkins (UID 1000:GID 1000) │
│ Process Supervisor │ Linux systemd init system │ Docker Engine / Containerd runtime │
│ Upgrade Mechanism │ apt-get / dnf upgrade │ docker compose pull && up -d │
├─────────────────────────┴──────────────────────────────┴──────────────────────────────────────┤
│ TOP 5 CORE INSTALLATION RULES FOR ENGINEERS: │
│ 1. Storage Choice: Deploy $JENKINS_HOME strictly on SSD/NVMe high-IOPS storage tiers. │
│ 2. JVM Version: Standardize across environments on OpenJDK 17 LTS or 21 LTS. │
│ 3. Memory Allocation: Maintain a 50/50 ratio between JVM Heap (-Xmx) and OS Page Cache. │
│ 4. Reverse Proxying: Always terminate TLS at an Nginx/ALB layer; never expose Jenkins raw. │
│ 5. Decoupled Compute: Ensure build executors on the controller remain set to ZERO. │
└───────────────────────────────────────────────────────────────────────────────────────────────┘