Setting Up Jenkins on Alpine Linux: Complete CI/CD Pipeline Guide

I’ll show you how to set up Jenkins on Alpine Linux for a robust CI/CD environment. After running Jenkins on various platforms, I’ve found Alpine provides the perfect balance of efficiency and security for automation servers.

Introduction

Jenkins on Alpine Linux is a winning combination for CI/CD infrastructure. Alpine’s minimal footprint means faster container builds and deployments, while Jenkins’ extensive plugin ecosystem handles everything from simple builds to complex deployment pipelines.

I’ve been running Jenkins on Alpine in production for years. The lightweight nature means you can run more build agents, and the security-focused design reduces your attack surface significantly.

Why You Need This

• Build lightweight, efficient CI/CD infrastructure
• Reduce resource costs with minimal overhead
• Achieve faster build times and deployments
• Create secure, containerized automation environments

Prerequisites

You’ll need these things first:

• Alpine Linux server with at least 2GB RAM (4GB+ recommended)
• Java runtime environment (OpenJDK)
• Internet connectivity for plugin downloads
• Basic understanding of CI/CD concepts
• Root access to the system

Step 1: Install Java Runtime

Install OpenJDK

Jenkins requires Java to run. Let’s install the latest LTS version.

What we’re doing: Installing OpenJDK 17 which is the recommended version for Jenkins.

# Update package repositories
apk update && apk upgrade

# Install OpenJDK 17 and related packages
apk add \
    openjdk17-jre \
    openjdk17-jdk \
    ca-certificates \
    curl \
    wget \
    git \
    bash

# Verify Java installation
java -version
javac -version

# Set JAVA_HOME environment variable
echo 'export JAVA_HOME=/usr/lib/jvm/java-17-openjdk' >> /etc/profile
echo 'export PATH=$JAVA_HOME/bin:$PATH' >> /etc/profile
source /etc/profile

Code explanation:

• openjdk17-jre: Java Runtime Environment for running Jenkins
• openjdk17-jdk: Java Development Kit for building Java projects
• ca-certificates: SSL certificates for HTTPS connections
• git: Version control system needed for most CI/CD workflows

Expected Output:

openjdk version "17.0.8" 2023-07-18
OpenJDK Runtime Environment (build 17.0.8+7-alpine-r1)
OpenJDK 64-Bit Server VM (build 17.0.8+7-alpine-r1, mixed mode, sharing)

Install Additional Build Tools

What we’re doing: Installing common tools needed for various build environments.

# Install build essentials
apk add \
    make \
    gcc \
    g++ \
    libc-dev \
    python3 \
    py3-pip \
    nodejs \
    npm

# Install Docker for containerized builds
apk add docker
rc-update add docker default
service docker start

# Add jenkins user to docker group (we'll create this user later)
# addgroup jenkins docker

Step 2: Install Jenkins

Download and Install Jenkins

What we’re doing: Installing Jenkins LTS from the official repository.

# Create jenkins user
adduser -D -s /bin/sh jenkins
addgroup jenkins docker

# Create Jenkins directories
mkdir -p /var/lib/jenkins
mkdir -p /var/log/jenkins
mkdir -p /etc/jenkins

# Set proper ownership
chown jenkins:jenkins /var/lib/jenkins
chown jenkins:jenkins /var/log/jenkins
chown jenkins:jenkins /etc/jenkins

# Download Jenkins LTS WAR file
cd /opt
wget https://get.jenkins.io/war-stable/latest/jenkins.war
chown jenkins:jenkins jenkins.war

# Create Jenkins configuration file
cat > /etc/jenkins/jenkins.conf << 'EOF'
JENKINS_HOME="/var/lib/jenkins"
JENKINS_USER="jenkins"
JENKINS_GROUP="jenkins"
JENKINS_WAR="/opt/jenkins.war"
JENKINS_JAVA_OPTIONS="-Djava.awt.headless=true -Xmx1024m -Xms512m"
JENKINS_PORT="8080"
JENKINS_LISTEN_ADDRESS="0.0.0.0"
JENKINS_ARGS="--httpPort=$JENKINS_PORT --httpListenAddress=$JENKINS_LISTEN_ADDRESS"
EOF

Configuration explanation:

• JENKINS_HOME: Directory where Jenkins stores all data
• JENKINS_JAVA_OPTIONS: JVM settings for memory allocation
• JENKINS_PORT: Port Jenkins listens on (default 8080)
• JENKINS_ARGS: Additional Jenkins startup arguments

Create Jenkins Service

What we’re doing: Setting up Jenkins as a system service with OpenRC.

# Create Jenkins init script
cat > /etc/init.d/jenkins << 'EOF'
#!/sbin/openrc-run

name="jenkins"
description="Jenkins Continuous Integration Server"

: ${jenkins_user:="jenkins"}
: ${jenkins_group:="jenkins"}
: ${jenkins_home:="/var/lib/jenkins"}

command="/usr/bin/java"
command_args="-Djava.awt.headless=true \
    -DJENKINS_HOME=${jenkins_home} \
    -Xmx1024m -Xms512m \
    -jar /opt/jenkins.war \
    --httpPort=8080 \
    --httpListenAddress=0.0.0.0"

command_user="${jenkins_user}:${jenkins_group}"
command_background=true
pidfile="/run/jenkins.pid"
output_log="/var/log/jenkins/jenkins.log"
error_log="/var/log/jenkins/jenkins.log"

depend() {
    need net
    after firewall
    use dns logger
}

start_pre() {
    checkpath -d -m 0755 -o ${jenkins_user}:${jenkins_group} ${jenkins_home}
    checkpath -d -m 0755 -o ${jenkins_user}:${jenkins_group} /var/log/jenkins
    checkpath -f -m 0644 -o ${jenkins_user}:${jenkins_group} /var/log/jenkins/jenkins.log
}
EOF

# Make service executable
chmod +x /etc/init.d/jenkins

# Enable Jenkins service
rc-update add jenkins default

# Start Jenkins
service jenkins start

# Check service status
service jenkins status

Verify Installation

What we’re doing: Confirming Jenkins is running and accessible.

# Check if Jenkins is listening
netstat -ln | grep 8080

# Check Jenkins logs
tail -f /var/log/jenkins/jenkins.log

# Wait for Jenkins to fully start (takes 1-2 minutes)
sleep 60

# Get initial admin password
cat /var/lib/jenkins/secrets/initialAdminPassword

Tip: Save the initial admin password! You’ll need it for the web setup wizard.

Step 3: Configure Jenkins Web Interface

Initial Setup Wizard

What we’re doing: Completing the Jenkins setup through the web interface.

# Display the initial admin password
echo "Jenkins initial admin password:"
cat /var/lib/jenkins/secrets/initialAdminPassword

# Check Jenkins is accessible
curl -I http://localhost:8080

echo "Access Jenkins at: http://your-server-ip:8080"
echo "Use the password above to unlock Jenkins"

Web setup steps:

1. Navigate to http://your-server-ip:8080 in your browser
2. Enter the initial admin password
3. Choose “Install suggested plugins” for a standard setup
4. Create your admin user account
5. Configure Jenkins URL (use your server’s IP or domain)
6. Click “Start using Jenkins”

Install Essential Plugins

What we’re doing: Installing additional plugins for common CI/CD workflows.

# Jenkins will be accessible via web interface
# Install these plugins through Manage Jenkins > Manage Plugins:
# - Blue Ocean (modern pipeline UI)
# - Docker Pipeline
# - Git Plugin (usually pre-installed)
# - Pipeline Stage View
# - Build Timeout
# - Timestamper
# - Workspace Cleanup
# - Credentials Binding
# - NodeJS Plugin
# - Python Plugin

Step 4: Configure Security and Performance

Set Up Security

What we’re doing: Configuring Jenkins security settings for production use.

Access Manage Jenkins > Configure Global Security and apply these settings:

# Security Realm: Jenkins' own user database
# Authorization: Matrix-based security
# Enable "Allow users to sign up" (disable in production)
# CSRF Protection: Enable
# Agent/Master Security: Enable

Create additional users through web interface:

• Developer users with build permissions
• Read-only users for stakeholders
• Service accounts for automated systems

Configure System Settings

What we’re doing: Optimizing Jenkins performance and functionality.

# Edit Jenkins configuration for better performance
cat >> /etc/jenkins/jenkins.conf << 'EOF'

# Increase memory for larger projects
JENKINS_JAVA_OPTIONS="-Djava.awt.headless=true -Xmx2048m -Xms1024m -XX:MaxMetaspaceSize=512m"

# Configure workspace cleanup
JENKINS_ARGS="$JENKINS_ARGS --sessionTimeout=60 --sessionEviction=3600"
EOF

# Restart Jenkins to apply changes
service jenkins restart

Set Up Backup Strategy

What we’re doing: Creating automated backups of Jenkins configuration.

# Create backup script
cat > /usr/local/bin/jenkins_backup.sh << 'EOF'
#!/bin/sh
# Jenkins backup script

BACKUP_DIR="/var/backups/jenkins"
JENKINS_HOME="/var/lib/jenkins"
DATE=$(date +%Y%m%d_%H%M%S)

# Create backup directory
mkdir -p $BACKUP_DIR

# Stop Jenkins for consistent backup
service jenkins stop

# Create compressed backup
tar -czf "$BACKUP_DIR/jenkins_backup_$DATE.tar.gz" \
    -C $JENKINS_HOME \
    --exclude="workspace/*" \
    --exclude="builds/*/workspace/*" \
    --exclude="logs/*" \
    .

# Start Jenkins
service jenkins start

# Clean old backups (keep 7 days)
find $BACKUP_DIR -name "jenkins_backup_*.tar.gz" -mtime +7 -delete

echo "Backup completed: $BACKUP_DIR/jenkins_backup_$DATE.tar.gz"
EOF

# Make backup script executable
chmod +x /usr/local/bin/jenkins_backup.sh

# Test backup
/usr/local/bin/jenkins_backup.sh

# Schedule daily backups
echo "0 3 * * * root /usr/local/bin/jenkins_backup.sh" >> /etc/crontabs/root

Step 5: Create Build Pipelines

Create a Simple Pipeline

What we’re doing: Setting up a basic CI pipeline for a Node.js project.

1. Create New Item in Jenkins web interface
2. Choose Pipeline project type
3. Name it “nodejs-pipeline”
4. In Pipeline section, use this script:

pipeline {
    agent any
    
    tools {
        nodejs 'NodeJS-18'  // Configure in Global Tool Configuration
    }
    
    environment {
        NODE_ENV = 'test'
    }
    
    stages {
        stage('Checkout') {
            steps {
                git branch: 'main', url: 'https://github.com/your-org/your-repo.git'
            }
        }
        
        stage('Install Dependencies') {
            steps {
                sh 'npm install'
            }
        }
        
        stage('Run Tests') {
            steps {
                sh 'npm test'
            }
            post {
                always {
                    publishTestResults testResultsPattern: 'test-results.xml'
                }
            }
        }
        
        stage('Build') {
            steps {
                sh 'npm run build'
            }
        }
        
        stage('Archive Artifacts') {
            steps {
                archiveArtifacts artifacts: 'dist/**/*', fingerprint: true
            }
        }
    }
    
    post {
        always {
            cleanWs()
        }
        success {
            echo 'Pipeline succeeded!'
        }
        failure {
            echo 'Pipeline failed!'
        }
    }
}

Configure Docker Pipeline

What we’re doing: Creating a containerized build pipeline.

pipeline {
    agent any
    
    environment {
        DOCKER_IMAGE = 'myapp'
        DOCKER_TAG = "${BUILD_NUMBER}"
    }
    
    stages {
        stage('Checkout') {
            steps {
                git 'https://github.com/your-org/docker-app.git'
            }
        }
        
        stage('Build Docker Image') {
            steps {
                script {
                    docker.build("${DOCKER_IMAGE}:${DOCKER_TAG}")
                }
            }
        }
        
        stage('Test Container') {
            steps {
                script {
                    docker.image("${DOCKER_IMAGE}:${DOCKER_TAG}").inside {
                        sh 'npm test'
                    }
                }
            }
        }
        
        stage('Push to Registry') {
            when {
                branch 'main'
            }
            steps {
                script {
                    docker.withRegistry('https://your-registry.com', 'registry-credentials') {
                        docker.image("${DOCKER_IMAGE}:${DOCKER_TAG}").push()
                        docker.image("${DOCKER_IMAGE}:${DOCKER_TAG}").push('latest')
                    }
                }
            }
        }
    }
}

Practical Examples

Example 1: Multi-Branch Pipeline

What we’re doing: Setting up automatic pipeline execution for different branches.

// Jenkinsfile in your repository
pipeline {
    agent any
    
    stages {
        stage('Build') {
            steps {
                echo "Building branch: ${env.BRANCH_NAME}"
                sh 'make build'
            }
        }
        
        stage('Test') {
            parallel {
                stage('Unit Tests') {
                    steps {
                        sh 'make test-unit'
                    }
                }
                stage('Integration Tests') {
                    steps {
                        sh 'make test-integration'
                    }
                }
            }
        }
        
        stage('Deploy to Staging') {
            when {
                branch 'develop'
            }
            steps {
                sh 'make deploy-staging'
            }
        }
        
        stage('Deploy to Production') {
            when {
                branch 'main'
            }
            steps {
                input message: 'Deploy to production?', ok: 'Deploy'
                sh 'make deploy-production'
            }
        }
    }
}

Example 2: Matrix Build

What we’re doing: Testing across multiple environments simultaneously.

pipeline {
    agent none
    
    stages {
        stage('Build Matrix') {
            matrix {
                axes {
                    axis {
                        name 'NODE_VERSION'
                        values '16', '18', '20'
                    }
                    axis {
                        name 'OS'
                        values 'alpine', 'ubuntu'
                    }
                }
                stages {
                    stage('Test') {
                        agent {
                            docker {
                                image "${OS}:latest"
                            }
                        }
                        steps {
                            sh "echo Testing on ${OS} with Node ${NODE_VERSION}"
                            sh "npm install"
                            sh "npm test"
                        }
                    }
                }
            }
        }
    }
}

Troubleshooting

Jenkins Won’t Start

Problem: Jenkins service fails to start Solution: Check Java installation and permissions

# Check Java version
java -version

# Check Jenkins logs
tail -f /var/log/jenkins/jenkins.log

# Verify file permissions
ls -la /var/lib/jenkins
ls -la /opt/jenkins.war

# Check available memory
free -h

# Restart with verbose logging
su - jenkins -c "java -jar /opt/jenkins.war --httpPort=8080"

Build Failures

Problem: Pipeline builds failing unexpectedly Solution: Debug build environment and dependencies

# Check build node resources
df -h
free -h

# Verify tool installations
which node npm git docker

# Check Docker daemon
service docker status
docker ps

# Review build logs in Jenkins UI
# Navigate to Build > Console Output

Performance Issues

Problem: Jenkins running slowly or timing out Solution: Optimize memory and concurrent builds

# Increase Jenkins memory
vi /etc/jenkins/jenkins.conf
# Set: JENKINS_JAVA_OPTIONS="-Xmx4096m -Xms2048m"

# Limit concurrent builds
# In Jenkins UI: Manage Jenkins > Configure System
# Set "# of executors" to number of CPU cores

# Clean up old builds
# In job configuration, set "Discard old builds"

Best Practices

1. Security Hardening:

   # Use HTTPS in production
   # Enable CSRF protection
   # Regular security updates
   apk upgrade
   
   # Limit network access
   iptables -A INPUT -p tcp --dport 8080 -s 192.168.1.0/24 -j ACCEPT

2. Pipeline Best Practices:

   • Use declarative pipeline syntax
   • Store Jenkinsfiles in version control
   • Implement proper error handling
   • Use parallel stages when possible

3. Resource Management:

   • Monitor disk space in JENKINS_HOME
   • Set up log rotation
   • Archive only necessary artifacts
   • Use shared libraries for common code

Verification

To verify your Jenkins installation is working correctly:

# Check service status
service jenkins status

# Verify web interface
curl -I http://localhost:8080

# Test a simple build
# Create a freestyle project that runs: echo "Hello World"

# Check logs
tail -f /var/log/jenkins/jenkins.log

# Verify plugins are loaded
# Access Manage Jenkins > System Information

Wrapping Up

You just set up a production-ready Jenkins CI/CD server on Alpine Linux:

• Installed Java runtime and Jenkins with proper user setup
• Configured security settings and user management
• Set up automated backup procedures
• Created sample pipelines for different project types
• Implemented monitoring and troubleshooting practices

This setup gives you a lightweight, efficient automation platform that’s perfect for everything from simple builds to complex deployment pipelines. Alpine’s minimal footprint means faster builds and deployments, while Jenkins’ flexibility handles any workflow you can imagine.