JENKINS PRODUCTION INSTALLATION: LINUX BARE-METAL, SYSTEMD & DOCKER

Enterprise systems engineering guide for B.Tech DevOps & Cloud Engineers: Hardware sizing criteria, OpenJDK runtime selection, Debian/Ubuntu & RHEL/CentOS systemd deployments, Docker Compose orchestration with persistent storage, Nginx reverse proxy SSL termination, and baseline security hardening.

🚀 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.

1. Hardware Sizing, Prerequisites & JVM Runtime Selection
Production hardware requirements, IOPS baselines, OpenJDK version support matrix, and initial OS firewall configurations.
Infrastructure Sizing Matrix & Hardware Footprint
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).
Production Guideline: Do not allocate 100% of host RAM to the Jenkins JVM heap. Jenkins relies heavily on operating system page caching for file I/O operations and disk operations inside $JENKINS_HOME. On a 16 GB server, allocate 8 GB to the JVM heap (-Xmx8g -Xms8g) and leave the remaining 8 GB for system buffers and daemon processes.
2. Debian / Ubuntu Production Installation (APT Repository & Systemd)
Configuring the official Jenkins Long Term Support (LTS) repository, installing OpenJDK 17, registering the GPG package signing key, and bootstrapping systemd.
Bash (Debian / Ubuntu 22.04 / 24.04 LTS Installation Commands)
#!/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
Verification Output: ● jenkins.service - Jenkins Continuous Integration Server Loaded: loaded (/lib/systemd/system/jenkins.service; enabled; vendor preset: enabled) Active: active (running) since Fri 2026-11-06 06:14:22 UTC; 8s ago Main PID: 14210 (java) Tasks: 48 (limit: 19137) Memory: 1.1G CPU: 12.841s CGroup: /system.slice/jenkins.service └─14210 /usr/bin/java -Djava.awt.headless=true -jar /usr/share/java/jenkins.war --webroot=/var/cache/jenkins/war --httpPort=8080
3. RHEL / CentOS / Rocky Linux / AlmaLinux Installation (RPM & DNF)
RPM-based installation pipeline using DNF, importing the Red Hat GPG key, configuring SELinux policies, and opening firewalld ports.
Bash (RHEL 8/9, Rocky Linux & AlmaLinux Installation Script)
#!/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
SELinux Hardening Notice: If SELinux is set to 'Enforcing', ensure that the service can bind to non-standard ports or write to custom directory locations. If placing $JENKINS_HOME on an external mount point (e.g., /mnt/data/jenkins), apply the correct SELinux context: sudo chcon -Rt var_lib_t /mnt/data/jenkins
4. Docker Installation: Compose, Persistent Volumes & UID Mapping
Deploying the official Jenkins controller image (jenkins/jenkins:lts-jdk17) using Docker Compose. Enforcing correct volume permissions using host UID/GID 1000:1000 mapping.
YAML (Production docker-compose.yml Configuration)
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
Bash (Host Directory Setup & Permission Provisioning)
# 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
Permission Failure Trap: If Jenkins fails to boot inside Docker with 'java.io.IOException: Permission denied' while creating /var/jenkins_home/copy_reference_file.log, the host volume directory lacks ownership permissions for UID 1000. Running 'sudo chown -R 1000:1000 /opt/jenkins_data' immediately resolves this failure mode.
5. Systemd Service Deep Configuration & JVM Heap Optimization
Customizing the systemd service unit via systemctl edit jenkins. Tuning the Garbage First Collector (G1GC), heap allocation limits, and file descriptor limits (nofile).
Systemd Override Configuration (/etc/systemd/system/jenkins.service.d/override.conf)
# 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
Bash (Reloading and Verifying Active Systemd Properties)
# 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"
Process Inspection Output: Max open files 65536 65536 files /usr/bin/java -Djava.awt.headless=true -Duser.timezone=UTC -Xms8g -Xmx8g -XX:+UseG1GC -jar /usr/share/java/jenkins.war
6. Reverse Proxy Setup: Nginx with Let's Encrypt SSL/TLS Termination
Production Nginx reverse proxy configuration. Handles HTTPS termination, WebSocket upgrades, proxy headers, and disables broken reverse proxy warnings.
Nginx (/etc/nginx/sites-available/jenkins.conf)
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;
    }
}
Configuration Verification: sudo nginx -t nginx: the configuration file /etc/nginx/nginx.conf syntax is ok nginx: configuration file /etc/nginx/nginx.conf test is successful sudo systemctl reload nginx
7. Post-Installation Wizard: Admin Secret, Plugins & Security Baseline
Locating the initial setup secret, completing the web setup wizard, selecting stable curated plugins, and establishing the primary administrator account.
Bash (Extracting Initial Setup Secret & Post-Boot Verification)
# 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-Installation Checklist & Security Baselines
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).
Security Audit Notice: Never leave the setup wizard unfinished. An unconfigured Jenkins instance on an open network will allow any remote user to claim administrative ownership over the controller.
8. Common Installation Failures & Troubleshooting Playbook
Analysis of frequent installation roadblocks, JVM crashes, port conflicts, package signature errors, and step-by-step remediations.
Diagnostic Commands & Remediation Playbook
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
Diagnostic Command: When debugging startup failures, inspect raw logs directly using: sudo journalctl -u jenkins -f -n 100 --no-tail
9. Installation Architectural Specification & Exam Reference Matrix
Technical summary mapping deployment patterns, directories, default files, and academic examination definitions for B.Tech students.
Production Deployment Specification Reference Matrix
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.            │
└───────────────────────────────────────────────────────────────────────────────────────────────┘
Academic & Professional Standard: Knowing how to properly provision, secure, and monitor a Jenkins controller is the starting point for infrastructure automation, pipeline engineering, and SRE operations across hybrid-cloud environments.