Jenkins with Docker Compose and Configuration as Code

This repository demonstrates how to create a Jenkins server using Docker Compose and Jenkins Configuration as Code (JCasC). The setup includes plugins, and supports both ARM and AMD architectures.

• Jenkins running in Docker - Containerized Jenkins server with persistent storage
• Configuration as Code (JCasC) - Automated setup with declarative configuration
• Pre-installed plugins:
  • Blue Ocean
  • Docker Pipeline
  • Configuration as Code
  • Docker Plugin
  • Workflow Aggregator
  • Matrix Authorization Strategy
• Multi-architecture support - ARM64 and AMD64 platforms
• Pre-configured users - Admin and devops users with role-based permissions
• Secrets-based password management - Secure password handling via Docker Compose secrets
• Automated setup script - Streamlined setup with setup-jenkins.sh
• Docker-in-Docker support - Build Docker images from Jenkins pipelines

• Docker Engine 20.10 or later
• Docker Compose 2.0 or later
• Docker Buildx (included with Docker Desktop) - For multi-arch builds

• Jenkins - Latest LTS with JDK 21
• Docker Compose - Container orchestration
• Jenkins Configuration as Code (JCasC) - Declarative configuration management
• Docker Cloud - Dynamic agent provisioning
• Docker-in-Docker - Docker socket mounting for pipeline builds

Use the setup-jenkins.sh script for automated setup:

./setup-jenkins.sh

The script will:

• Prompt for Jenkins URL and admin email
• Generate secure passwords automatically
• Create the .env file
• Optionally build the image
• Start Jenkins with Docker Compose

mkdir -p secrets
chmod 700 secrets
openssl rand -base64 32 > secrets/jenkins_admin_password
openssl rand -base64 32 > secrets/jenkins_devops_password
chmod 600 secrets/jenkins_admin_password secrets/jenkins_devops_password

JENKINS_URL=http://localhost:8080/
JENKINS_ADMIN_EMAIL=admin@example.com
DOCKER_SOCK_PATH=/var/run/docker.sock

docker compose up -d --build

./build-multiarch.sh
docker compose up -d

The Jenkins configuration is defined in jenkins.yaml. This file includes:

• Security Realm: Local user authentication with admin and devops users
• Authorization: Role-based access control with fine-grained permissions
• Docker Cloud: Configured for dynamic agent provisioning via Docker socket
• System Settings: Admin email, URL, and other system configurations (loaded from environment variables)

For detailed explanation: See JENKINS_CONFIG.md

The docker-compose.yaml file orchestrates the Jenkins container and includes:

• Service Configuration: Jenkins service with build, ports, volumes, and health checks
• Secrets Management: Docker Compose secrets for password handling
• Volume Mounts: Persistent storage and configuration file mounting
• Docker Socket: Mounted for Docker-in-Docker support
• Networking: Custom network for service isolation

For detailed explanation: See DOCKER_COMPOSE_CONFIG.md

Edit jenkins.yaml to customize:

• User accounts and permissions
• Jenkins system settings
• Docker cloud configuration
• Global libraries
• Tool installations

Important: Passwords are managed through Docker Compose secrets stored in the secrets/ directory. To change passwords, regenerate the secret files and restart Jenkins:

openssl rand -base64 32 > secrets/jenkins_admin_password
openssl rand -base64 32 > secrets/jenkins_devops_password
docker compose restart jenkins

Docker Cloud is a Jenkins feature that allows Jenkins to dynamically provision Docker containers as build agents on demand, rather than using static build agents.

What it does

Instead of maintaining permanent build agents, Jenkins can:

• Spin up Docker containers as build agents when jobs need them
• Run builds in isolated containers with clean environments
• Automatically tear down containers when builds complete (after idle timeout)
• Scale agents dynamically based on workload

Configuration

The Docker Cloud is configured in jenkins.yaml with the following settings:

• Instance Cap: Up to 10 containers can run simultaneously
• Agent Image: Uses jenkins/inbound-agent:lts-jdk21 for build agents
• Label: Jobs can request agents with the docker label
• Idle Timeout: Agents are removed after 5 minutes of inactivity
• Docker Socket: Connects to host Docker daemon via dynamically detected socket path

Example Pipeline Usage

pipeline {
    agent {
        label 'docker'
    }
    stages {
        stage('Build') {
            steps {
                sh 'echo "Building in Docker agent"'
            }
        }
    }
}

This setup includes Docker-in-Docker support, allowing Jenkins pipelines to build Docker images. The Docker socket is mounted from the host, enabling Jenkins to use the host's Docker daemon.

Note: The Jenkins container runs as the jenkins user (non-root) with docker group membership for secure Docker socket access. For production environments, consider using Docker-in-Docker containers or a separate Docker daemon.

• jenkins_home: Persistent storage for Jenkins data, configurations, and build history
• jenkins.yaml: Mounted as read-only configuration file for JCasC
• Docker Socket: Mounted from host for Docker-in-Docker support

• 8080: Jenkins web interface
• 50000: Jenkins agent communication port

Jenkins runs on a custom Docker network (jenkins-network) for service isolation. This allows for future expansion with additional services (databases, reverse proxies, etc.) that can communicate using service names as hostnames.

URL: http://localhost:8080

After starting Jenkins with Docker Compose, access the web interface at the configured URL (default: http://localhost:8080).

Two pre-configured users are available:

Admin User

• Username: admin
• Password: Stored in secrets/jenkins_admin_password
• Permissions: Full administrative access (Overall/Administer)

DevOps User

• Username: devops
• Password: Stored in secrets/jenkins_devops_password
• Permissions: Extensive job, agent, and credential management (but not Overall/Administer)

To view passwords:

cat secrets/jenkins_admin_password
cat secrets/jenkins_devops_password

URL: http://localhost:8080/blue

Blue Ocean provides a modern, intuitive user interface for Jenkins pipelines. It should be accessible after installation.

• Blue Ocean should be accessible at: http://localhost:8080/blue
• Docker Pipeline plugin should be available in pipeline configurations
• Configuration as Code plugin should show the applied configuration
• Docker Cloud should be configured in: Manage Jenkins → Nodes and Clouds → Clouds

• Secrets Management: Passwords managed via Docker Compose secrets stored in the secrets/ directory (git-ignored). Never commit plain-text passwords to version control.
• Non-Root User: Jenkins container runs as the jenkins user (non-root) with docker group membership for secure Docker socket access.
• Docker Socket Security: Docker socket is mounted with appropriate permissions. The container's docker group uses GID 999 (standard).
• Read-Only Configuration: JCasC configuration file (jenkins.yaml) is mounted as read-only to prevent accidental modification.
• Health Checks: Container health monitoring ensures Jenkins is running correctly.
• Log Rotation: Log files are rotated to prevent disk space issues and maintain security.

• Use the setup script: setup-jenkins.sh automatically generates secure passwords using openssl rand -base64 32
• Rotate passwords regularly: Regenerate secret files and restart Jenkins periodically
• Never commit secrets: The secrets/ directory and .env file are git-ignored
• Review permissions: Regularly review user permissions in jenkins.yaml
• Keep updated: Regularly update Jenkins and plugins to patch security vulnerabilities
• Production considerations: For production, consider using Docker-in-Docker containers or a separate Docker daemon instead of mounting the host socket

The Docker socket should be owned by root:docker with permissions srw-rw---- (typically mode 0660). Check with:

ls -l $DOCKER_SOCK_PATH

Or check your .env file for the detected path.

Common issues and solutions:

• Jenkins won't start: Check logs with docker compose logs jenkins, verify Docker socket permissions, ensure ports 8080 and 50000 are not in use
• Configuration not applied: Check JCasC logs in Jenkins (Manage Jenkins → System Log → Configuration as Code), verify jenkins.yaml syntax
• Docker socket permission denied: Verify socket ownership and permissions, check Docker group GID matches (999)
• Multi-arch build issues: Ensure Docker Buildx is installed, create a new builder with docker buildx create --name multiarch --use

For detailed troubleshooting information, see the Troubleshooting section in the README.

This repository includes comprehensive unit tests for the Jenkins configuration, covering:

• User authentication (admin and regular users)
• Admin permissions (Overall/Administer)
• User permissions (Job/Read, Job/Build, Job/Cancel, Job/Workspace, View/Read)
• Container health checks

For detailed information about running and maintaining the tests, see TEST_README.md.

GitHub Repository: docker-compose-and-jenkins-casc

This project is licensed under the MIT License.

See the LICENSE file for details.

Copyright (c) 2025 Tal Orlik