{"id":458,"date":"2025-10-14T01:55:00","date_gmt":"2025-10-14T01:55:00","guid":{"rendered":"https:\/\/blog.ngocha.biz\/?p=458"},"modified":"2025-10-14T01:55:00","modified_gmt":"2025-10-14T01:55:00","slug":"docker-containers-as-build-slaves-jenkins","status":"publish","type":"post","link":"https:\/\/blog.ngocha.biz\/?p=458","title":{"rendered":"How to Setup Docker containers as Build Agents for Jenkins"},"content":{"rendered":"

This article guides you to set up Jenkins build inside a Docker container using Docker-based Jenkins build agents.<\/p>\n

The resource utilization of the Jenkins agents is very less if you do not have builds happening continuously. It is better to use ephemeral Docker containers as Jenkins agents for better resource utilization in this scenario.<\/p>\n

As you know, spinning up a new container takes less than a minute; every build spins up a new container, builds the project, and is destroyed. This way, you can reduce the number of static Jenkins build VMs.<\/p>\n

Docker Containers as Build Agents\/Slaves<\/h2>\n

In this guide, I will walk you through the steps for configuring Docker Containers<\/a> as build agents.<\/p>\n

I assume that you have a Jenkins server up and running. If you do not have one, follow this tutorial. How to setup Jenkins 2<\/a><\/p>\n

If you want docker based Jenkins setup, you can follow this tutorial -> Setup Jenkins On a Docker container<\/a><\/p>\n

Let’s Implement It<\/strong><\/p>\n

Configure a Docker Host With Remote API [Important]<\/h2>\n

The first thing we should do is set up a docker host. Jenkins server will connect to this host for spinning up the build agent containers. I am going to use the Centos server as my docker host. You can use any OS which supports Docker.<\/p>\n

Jenkins master connects to the docker host using REST APIs. So we need to enable the remote API for our docker host.<\/p>\n

\"\"
Click to view in HD<\/span><\/figcaption><\/figure>\n

Make sure the following ports are enabled in your server firewall to accept connections from Jenkins master.<\/p>\n

<\/p>\n\n\n\n\n
Docker Remote API port<\/td>\n4243<\/td>\n<\/tr>\n
Docker Hostport Range<\/td>\n32768 to 60999 <\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

<\/p>\n

32768 to 60999<\/code> is used by Docker to assign a host port for Jenkins to connect to the container. Without this connection, the build slave would go in a pending state.<\/p>\n

Lets get started,<\/p>\n

Step 1: <\/strong>Spin up a VM, and install docker on it. You can follow the official documentation for installing docker. <\/a>based on the Linux distribution you use. Make sure the docker service is up and running.<\/p>\n

Step 2: L<\/strong>og in to the server and open the docker service file \/lib\/systemd\/system\/docker.service<\/code>. Search for ExecStart<\/code> and replace that line with the following.<\/p>\n

ExecStart=\/usr\/bin\/dockerd -H tcp:\/\/0.0.0.0:4243 -H unix:\/\/\/var\/run\/docker.sock<\/code><\/pre>\n
Step 3: <\/strong>Reload and restart docker service.<\/p>\n
sudo systemctl daemon-reload\nsudo service docker restart<\/code><\/pre>\n
Step 4: Validate API by executing the following curl commands. Replace 54.221.134.7<\/code> with your host IP.<\/p>\n
curl http:\/\/localhost:4243\/version\ncurl http:\/\/54.221.134.7:4243\/version<\/code><\/pre>\n
Check the docker remote API<\/a> article for a detailed explanation of Docker API.<\/p>\n
Once you enabled and tested the API, you can now start building the docker slave image.<\/p>\n
Create a Jenkins Agent Docker Image<\/h2>\n
I have created a Jenkins docker image for maven<\/a>. You can use this image or use its Dockerfile<\/a> as a reference for creating your own.<\/p>\n
If you are creating the image on your own, its image should contain the following minimum configurations to act as a slave.<\/p>\n
    \n
  1. sshd<\/code> service running on port 22.<\/li>\n
  2. Jenkins user with password.<\/li>\n
  3. All the required application dependencies for the build. For example, for a java maven project, you need to have git, java, and maven installed on the image.<\/li>\n<\/ol>\n
    Make sure the sshd<\/code> service is running and can be logged into the containers using a username and password. Otherwise, Jenkins will not be able to start the build process.<\/p>\n
    \n
    Note: <\/strong><\/b>The default ssh username is jenkins and the <\/strong><\/b>password is also jenkins<\/strong><\/b> as per the given Dockerfile. You will have to use these credentials in the below configuration.<\/div>\n<\/div>\n
    Configure Jenkins Server With Docker Plugin<\/h2>\n
    Step 1<\/strong>: Head over to Jenkins Dashboard –> Manage Jenkins –> Manage Plugins.<\/p>\n
    Step 2<\/strong>: Under the Available tab, search for “Docker” and install the docker cloud plugin and restart Jenkins. Here is the official plugin site<\/a>. Make sure you install the right plugin as shown below.<\/p>\n
    \"Install<\/figure>\n
    Step 3: <\/strong>Once installed, head over to Jenkins Dashboard –> Manage Jenkins –> Configure system.<\/p>\n
    Step 4<\/strong>: Under “Configure System<\/code>“, there will be a section named “cloud<\/strong>” at the last. There you can fill out the docker host parameters for spinning up the slaves.<\/p>\n
    Step 5:<\/strong> Under docker, you need to fill out the details as shown in the image below.<\/p>\n
    \n
    Note<\/strong><\/b>: Replace “Docker URI” with your docker host IP. For example, tcp:\/\/10.128.0.3:4243<\/code> You can use the “Test connection” to test if Jenkins is able to connect to the Docker host.<\/div>\n<\/div>\n
    \"configure<\/figure>\n
    Step 6:<\/strong> Now, from “Docker Agent Template<\/strong>” dropdown, click the <\/strong>“Add Docker template<\/strong>” and fill in the details based on the explanation and the image given below and save the configuration.<\/p>\n
      \n
    1. Labels<\/strong> – Identification for the docker host. It will be used in the Job configuration. Here we use java-docker-slave<\/code><\/li>\n
    2. Name:<\/strong> Name of the docker template. Here we use the same name as label ie, java-docker-slave<\/li>\n
    3. Docker Image<\/strong> – bibinwilson\/jenkins-slave:latest<\/code> or the image that you created for the slave.<\/li>\n
    4. Remote Filing System Root<\/strong> – Home folder for the user you have created. In our case, it’s \/home\/jenkins<\/li>\n
    5. Credentials<\/strong> – click add and enter the SSH username and password that you have created for the docker image. Leave the rest of the configuration as shown in the image below and click save. If you are using my Docker image, the user will be jenkins<\/code> & password is also  jenkins<\/code>.<\/li>\n<\/ol>\n
      \n
      Note:<\/strong><\/b> There are additional configurations like registry authentication and container settings that you might have to use when configuring this set up in the corporate network.<\/div>\n<\/div>\n
      \"Jenkins<\/figure>\n
      You can also use JNLP-based slave agents. For this, the configurations need a little change as shown below. Primarily the docker image name<\/code> and the connect method<\/code>.<\/p>\n
      \n
      Note:<\/strong><\/b> For JNLP to work, you need to enable the JNLP connection port (50000) in Jenkins’s global security configuration (TCP port for inbound agents)<\/code>. Also, the Jenkins master firewall should be able to accept this connection form the docker host.<\/div>\n<\/div>\n
      \"Docker<\/figure>\n
      By default, the workspace will not be persisted in the host. However, if you want the workspace to be persistent, add a host volume path under container settings.<\/p>\n
      For example, if you want the workspace to be available at \/home\/ubuntu<\/code>, you can add the volume path as shown below. \/home\/jenkins<\/code> is the path inside the container.<\/p>\n
      \/home\/ubuntu:\/home\/jenkins<\/code><\/pre>\n
      Towards the right of the Volumes option, if you click the question mark, it will show you additional volume options as shown below.<\/p>\n
      \"mount<\/figure>\n
      Building Docker Images using Docker Agents<\/h2>\n
      There are use cases where you have to build Docker images<\/a> in the CI process.<\/p>\n
      You can achieve that using Docker based Jenkins agent as well.<\/p>\n
      If you are planning to run docker in docker for your CI process, you can mount the host docker.sock<\/code> as volume to execute docker commands.<\/p>\n
      Check out my article on running docker in docker<\/a> to know how to run docker in docker.<\/p>\n
      Test Jenkins Build Inside a Docker container<\/h2>\n
      Now that you have the slave configurations ready, we will test the docker agent plugin using a freestyle job.<\/p>\n
        \n
      1. Create a freestyle job, select “Restrict where this project can be run<\/code>” option and select the docker host as a slave using the label.<\/li>\n
      2. Add a shell build step which echoes a simple “Hello World<\/code>“<\/li>\n<\/ol>\n
        \"Jenkins<\/figure>\n
        If you have done all the configurations right, Jenkins will spin up a container, builds the project, and destroys the container once the build is done.<\/p>\n
        First, you will see a pending notification as Jenkins tries to deploy a container on run time and establishes an SSH connection. After a few seconds, your job will start building.<\/p>\n
        \"\"<\/figure>\n
        You can check the build logs in your jobs console output as shown below.<\/p>\n
        \"\"<\/figure>\n
        Also, you can check out the video explaining the whole process.<\/p>\n