Note: I’m not using Docker at the moment, so I cannot guarantee that the following works anymore given the volume of updates to Docker and Jenkins.
This post describes how to:
- Install and configure Docker for use as a Jenkins-CI slave.
- Install and configure Jenkins-CI.
- Install and configure the Docker plugin for Jenkins-CI.
- Provide a working example of how to use the Docker plugin.
What you’ll need
- Two hosts running Linux. One for running Jenkins-CI the other for running Docker. I’ll be using Ubuntu for this how to but any distribution should do as long as it meets Jenkins and Docker’s requirements.
- Internet access. Ubuntu and Docker both need Internet access.
While you can do everything this how to describes on one host, by using two hosts you will get a feel for the master-slave configuration we are creating.
This how-tos’ servers are on a secure network, so the hosts’ firewalls are disabled to speed things up. If you are using CentOS, you will want to disable SELinux. In a production environment be sure to verify your environments security requirements before disabling any of these features.
# sudo stop ufw # sudo ufw disable
# service iptables stop # chkconfig iptales off # setenforce 0 # sed -i 's/=enforcing/=disabled/g' /etc/sysconfig/selinux
Setting up the Docker host
- Install the OS on what will be the Docker server. Make sure OpenSSH is installed, configured and running.
- Install Docker by following the instructions in the documentation, http://docs.docker.com/linux/step_one/.
- Once Docker is running properly, update the
/etc/default/docker(CentOS: /etc/sysconfig/docker) file to include the following:
DOCKER_OPTS="-H unix:///var/run/docker.sock -H tcp://0.0.0.0:2375"
-H unix:///var/run/docker.sockconfigures a local unix socket for Docker to use. This is the default.
-H tcp://0.0.0.0:2375option configures Docker to listen on a TCP port, a requirement for Jenkins to talk to Docker.
Restart Docker to enable the changes.
sudo restart docker
Optional: if you feel confident, add your user to the docker group so you will not have to prefix your docker command with
sudo all the time.
sudo usermod -aG docker myuser
You need to logout and login for the change to take effect.
Our example uses a Docker image created by the author of the Jenkins Docker Plugin. Download the
evarga/jenkins-slave image using the command:
sudo docker pull evarga/jenkins-slave
The time required to download the image depends on your Internet connection speed.
evarga/jenkins-slave image is a Debian image with a pre-configured jenkins user account.
Setting up the Jenkins server
- Install the OS on what will be the Jenkins-CI server. Make sure OpenSSH is installed, configured and running.
- Go to jenkins-ci.org and download the latest Jenkins-CI package. This how-to uses the current release, but the stable version should work.
Sample Jenkins installation process for Ubuntu:
wget -q -O - http://pkg.jenkins-ci.org/debian/jenkins-ci.org.key | sudo apt-key add - echo 'deb http://pkg.jenkins-ci.org/debian binary/' > /etc/apt/sources.list.d/jenkins.list sudo apt-get update sudo apt-get install jenkins sudo service jenkins start
– Install the Jenkins-CI package key.
– Configure the Jenkins-CI package repository.
– Install the Jenkins daemon and its dependencies.
– Start the Jenkins service.
Get the IP address (or hostname if DNS is configured) of your Jenkins host and using a browser connect to the Jenkins-CI host on port 8080. Example:
http://192.168.0.10:8080/ If everything worked, you’ll be greeted with a Welcome to Jenkins! page.
Note: Jenkins can take some time to start, so don't be surprised if you cannot connect right away.
By default, Jenkins-CI gives full access to the user. No user name or password is required to login. If you decide to roll-out your own setup in production, be sure to look into the various authentication and authorization options.
Installing and configuring the Jenkins Docker plugin
Installing the Docker plugin
- Using your browser, connect to your Jenkins server.
- From the main menu, select
Manage Jenkinsthen select
- If there are any updates available, install them before continuing.
- Click on the
- In the
Filterfield at the top of the page, type in
Docker. The list of
matching plugins will update automatically.
Docker pluginfrom the list.
- Click the
Download now and install after restartbutton at the bottom of
- You must now restart Jenkins manually (
service jenkins restart) or check off
Restart Jenkins when installation is complete and no jobs are runningbox
which will restart Jenkins-CI for you.
Configuring the Docker plugin
Configuring the Docker plugin is a two-step process. The first step is configuring the plugin to use our Docker server. The second step is configuring the list of Docker images available to Jenkins-CI on that server.
Adding the Docker server (aka, the cloud)
I’m only describing the fields required to configure the plugin. Each field’s help is accessed by clicking the field’s help icon (?).
- From the
Manage Jenkinsmenu, select
- Scroll down to the
Cloudsection. (Usually at the bottom on the page.)
- Click the
Add a new clouddrop down and select
Docker. A Docker sub-section is added to the Cloud section.
- Now fill in the Docker cloud section.
Name: Enter a name for the docker cloud. This is purely a label and can be anything.
Docker URL: Enter the URL of our Docker server including the port number. This is the IP or hostname of the Docker server we created earlier. Example:
Credentials: We didn’t configure our Docker server to use credentials so leave it set to
Container Cap: The number of Docker containers we can run at any one time on the Docker server.
- Click the
Test Connectionto test the configuration. The Docker version running on the server is returned if everything is correct.
The server is now configured and we can move on to configuring the images to use.
Configuring the Docker images to use
I’m only describing the fields required. Each field’s help can be accessed by clicking the field’s help icon (?).
- In Cloud’s Docker sub-section, click the
Add Docker Templatedrop down and select
Docker Template. An empty Docker Template gets added to the section.
- Fill in the Docker Template.
Docker Image: This is the name of the docker image to use. Our example uses the image we downloaded earlier,
Remote Filing System Root: This is the path to the Jenkins home directory inside the Docker image. If you use another Docker image, you probably need to adjust this value.
Labels: This is the label to assign to this image. This is the label that appears in other parts of Jenkins, including restrictions. I suggest a label based on the image name. Our example uses
Launch method: This is how Jenkins will log in to the running Docker image. By default there is only the SSH option which is what we’ll use.
- Next to the empty
Credentialsdrop down, click the
Addbutton to open the
Add credentialsdialog. The username and password are already configured in the Docker image and have been provided by the image’s author.
Kind: Username with password
Description: Enter a description of the credentials. For example:
evarga/jenkins-slave ssh credentials.
Addand the credentials will be added to Jenkins. Because this is the first set of credentials we created they will automatically be selected.
- Click the
Savebutton at the bottom of the page.
That’s it. The Docker plugin is now ready for use.
A quick example
Here is a quick example of how to use the docker plugin in a job.
- Enter a name for the job.
- Select the
OK. You’ll be taken to the project’s configuration page.
- Enable the
- Make sure
Restrict where this project can be runis selected.
- In the
Label Expressionfield, enter
evarga-jenkins-slave. Jenkins attempts to auto-complete the label from the list of labels previously defined. Jenkins will display an error if it cannot find the label you enter.
Add build stepand select
- We’ll use a simple script. Copy and paste the code into the
#!/bin/bash env echo "hello from docker!" exit $?
- Click the
Unlike a locally run job, the Docker slave jobs can take a minute or two to
If everything worked, the output from the job should look like the following:
Started by user anonymous Building remotely on our-docker-cloud-451be36e99da (evarga-jenkins-slave) in workspace /home/jenkins/workspace/testjob [testjob] $ /bin/bash /tmp/hudson4153896756936909309.sh BUILD_URL=http://172.16.210.43:8080/job/testjob/1/ HUDSON_SERVER_COOKIE=5b6b248fca7784cf SHELL=/bin/bash SSH_CLIENT=172.16.210.43 60438 22 DOCKER_HOST=tcp://172.16.210.34:2375 BUILD_TAG=jenkins-testjob-1 WORKSPACE=/home/jenkins/workspace/testjob JOB_URL=http://172.16.210.43:8080/job/testjob/ USER=jenkins JENKINS_HOME=/var/lib/jenkins PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games MAIL=/var/mail/jenkins _=/usr/bin/env PWD=/home/jenkins/workspace/testjob HUDSON_URL=http://172.16.210.43:8080/ JOB_NAME=testjob BUILD_DISPLAY_NAME=#1 JENKINS_URL=http://172.16.210.43:8080/ BUILD_ID=1 DOCKER_CONTAINER_ID=451be36e99dabf23221bfc627462d5d61b8c24971b74a814e04aa270d66fef2b HOME=/home/jenkins SHLVL=2 JENKINS_SERVER_COOKIE=5b6b248fca7784cf EXECUTOR_NUMBER=0 NODE_LABELS=evarga-jenkins-slave our-docker-cloud-451be36e99da LOGNAME=jenkins JENKINS_CLOUD_ID=our-docker-cloud HUDSON_HOME=/var/lib/jenkins SSH_CONNECTION=172.16.210.43 60438 172.31.31.99 22 NODE_NAME=our-docker-cloud-451be36e99da BUILD_NUMBER=1 HUDSON_COOKIE=285ada53-ada0-48d1-9766-f806a2e45e7f hello from docker! Finished: SUCCESS
Congratulations! You know have a working Jenkins-CI setup using Docker for SSH build slaves.