How To Add A Jenkins Agent Using Docker Compose

|

In modern CI/CD pipelines, Jenkins remains a cornerstone for automation. While its master-agent architecture makes it highly scalable, setting up Jenkins agents can be tedious—especially in dynamic or containerized environments. Docker Compose provides a lightweight and declarative way to configure and launch multiple containers, making it an excellent tool for defining Jenkins master and agents.

In this article, we’ll walk through how to add a Jenkins agent using Docker Compose, with detailed steps, configurations, and example YAML and Dockerfiles to ensure you’re ready to integrate agents seamlessly into your CI/CD pipeline.

Understanding the Jenkins Master-Agent Model

Jenkins operates using a master-agent architecture:

  • Master: The primary Jenkins server that orchestrates jobs.

  • Agent: A node (virtual machine or container) that executes build steps.

Agents are especially useful for:

  • Isolating different environments (e.g., Node.js vs Java builds),

  • Parallelizing workloads,

  • Offloading tasks from the master for better performance.

Why Use Docker Compose for Jenkins Agents?

Docker Compose simplifies multi-container configurations and avoids manual network, volume, and dependency management. Benefits include:

  • Declarative service definitions,

  • Built-in networking between master and agent containers,

  • Persistent volumes for Jenkins home,

  • Scalability through service replication.

Prerequisites

Make sure the following tools are installed:

  • Docker Engine

  • Docker Compose (v2 or above)

  • Basic knowledge of YAML and Dockerfiles

Set Up the Project Directory

Create a directory for your Jenkins setup:

bash
mkdir jenkins-docker-compose
cd jenkins-docker-compose

Inside this folder, create the following structure:

markdown
.
├── docker-compose.yml
├── jenkins
│ └── Dockerfile
└── agent
└── Dockerfile

Create the Jenkins Master Dockerfile

In the jenkins/Dockerfile, add the following:

Dockerfile

FROM jenkins/jenkins:lts

USER root

# Install Docker CLI (optional: useful for docker-in-docker)
RUN apt-get update && apt-get install -y docker.io

# Give Jenkins user permissions to use Docker
RUN usermod -aG docker jenkins

USER jenkins

This Dockerfile extends the official Jenkins LTS image and optionally installs Docker CLI for builds that need Docker-in-Docker capabilities.

Create the Jenkins Agent Dockerfile

In the agent/Dockerfile, add:

Dockerfile

FROM jenkins/inbound-agent:latest-jdk11

USER root

# Optional: install Docker CLI if needed for builds
RUN apt-get update && apt-get install -y docker.io

USER jenkins

The jenkins/inbound-agent image is a prebuilt Jenkins agent that connects back to the master via the JNLP (Java Network Launch Protocol).

Create the Docker Compose File

In the root docker-compose.yml, define the services:

yaml

version: '3.8'

services:
jenkins-master:
build: ./jenkins
container_name: jenkins-master
ports:
– “8080:8080”
– “50000:50000”
volumes:
– jenkins_home:/var/jenkins_home
networks:
– jenkins-net

jenkins-agent:
build: ./agent
container_name: jenkins-agent
depends_on:
– jenkins-master
environment:
– JENKINS_URL=http://jenkins-master:8080
– JENKINS_AGENT_NAME=agent01
– JENKINS_SECRET=
networks:
– jenkins-net

volumes:
jenkins_home:

networks:
jenkins-net:

At this stage, we leave JENKINS_SECRET empty. It will be filled in after setting up the agent on the Jenkins UI.

Start Jenkins Master

Run:

bash
docker compose up --build -d

Open Jenkins in your browser:

arduino
http://localhost:8080

To unlock Jenkins:

bash
docker exec jenkins-master cat /var/jenkins_home/secrets/initialAdminPassword

Use the password to unlock the UI and install recommended plugins.

Create an Agent Node in Jenkins UI

  1. Navigate to Manage Jenkins → Nodes → New Node

  2. Enter a name (agent01) and select Permanent Agent

  3. Configure:

    • Remote root directory: /home/jenkins/agent

    • Labels: docker-agent

    • Launch Method: Launch agent via Java Web Start (inbound agent)

  4. Save the configuration.

After saving, Jenkins will provide a Secret and a JNLP URL like:

bash
java -jar agent.jar -jnlpUrl http://jenkins-master:8080/computer/agent01/slave-agent.jnlp -secret xxxxxxxxxxxx

Update the Docker Compose File with Secret

Edit docker-compose.yml and update the jenkins-agent section:

yaml
jenkins-agent:
build: ./agent
container_name: jenkins-agent
depends_on:
- jenkins-master
environment:
- JENKINS_URL=http://jenkins-master:8080
- JENKINS_AGENT_NAME=agent01
- JENKINS_SECRET=xxxxxxxxxxxx # From previous step
networks:
- jenkins-net

Restart the agent:

bash
docker compose up -d --no-deps --build jenkins-agent

Verify Agent Connection

Go to Manage Jenkins → Nodes, and the agent agent01 should show as Online.

You can now use this agent in your pipeline jobs by adding:

groovy
agent { label 'docker-agent' }

Automate with Groovy Initialization Script

To fully automate agent registration, create an init.groovy.d script:

groovy
import jenkins.model.*
import hudson.slaves.*def instance = Jenkins.getInstance()def dockerAgent = new DumbSlave(
“agent01”,
“/home/jenkins/agent”,
new JNLPLauncher()
)
dockerAgent.numExecutors = 2
dockerAgent.labelString = “docker-agent”
dockerAgent.mode = Node.Mode.NORMAL
dockerAgent.retentionStrategy = new RetentionStrategy.Always()instance.addNode(dockerAgent)
instance.save()

Place this in /var/jenkins_home/init.groovy.d/ via Dockerfile or mounted volume.

Troubleshooting Tips

  • Agent not connecting: Check that the JENKINS_SECRET and JENKINS_AGENT_NAME match Jenkins configuration.

  • Firewall or network issues: Make sure port 50000 is open between master and agent.

  • Plugin conflicts: Verify you’re using compatible versions of the inbound-agent and Jenkins core.

Jenkins Pipeline Example Using the Agent

Here’s a sample Jenkinsfile that uses the agent:

groovy
pipeline {
agent { label 'docker-agent' }
stages {
stage('Build') {
steps {
echo 'Building...'
}
}
stage('Test') {
steps {
echo 'Running tests...'
}
}
}
}

Save this Jenkinsfile in a Git repository and configure a pipeline job to point to it.

Scaling with Docker Compose

You can scale your agents horizontally with:

bash
docker compose up --scale jenkins-agent=3 -d

This spins up three agent containers, each needing separate names and secrets. You’ll need to create corresponding agent configurations in Jenkins or automate them via scripting.

Security Considerations

  • Limit JNLP agents to trusted environments.

  • Use HTTPS for Jenkins communication.

  • Isolate Jenkins containers using custom networks.

  • Regularly update images to patch vulnerabilities.

Conclusion

Adding Jenkins agents using Docker Compose offers a repeatable, scalable, and efficient approach to extending your CI/CD infrastructure. Instead of manually configuring each node, you can leverage Compose to declare infrastructure as code, seamlessly spin up environments, and even scale horizontally with ease.

By using prebuilt agent containers and linking them to the master over an internal Docker network, you minimize setup friction and maximize environment parity. Integrating secrets and auto-launch mechanisms helps achieve true automation, and with a Groovy script or plugin-based registration, you can scale further into dynamic or ephemeral agents.

Whether you’re a solo developer or running enterprise-level pipelines, Docker Compose gives you the flexibility to iterate faster and deploy with confidence. Start small with a single agent, and soon you’ll find yourself orchestrating a robust Jenkins architecture with just a few YAML lines and a couple of Dockerfiles.