dair-jenkins-guide

Jenkins for DAIR

This guide will show you how to launch and configure a basic Jenkins setup using Docker.

Prerequisites

You should have previously completed the DAIR Docker Technical Primer to be familiar with launching Docker hosts in DAIR using Docker Machine.

You will also need to install Docker Compose on the same machine that you've been using to run the Docker Machine commands. Follow the instructions from the official install guide. If you're using Docker for Mac or Docker for Windows you'll already have installed.

Finally you'll need Git to clone this repository, take a look at the official install guide if you're unfamiliar. Alternatively you can download this repository as a zip archive instead.

Setup

All of these commands should be run on the machine you have installed Docker Machine and Compose.

First, clone this repository:

git clone https://github.com/cybera/dair-jenkins-guide
cd dair-jenkins-guide

Before moving to the second step, verify that you are configured to deploy to the DAIR instance you've created.

docker-machine active

If you're not set to deploy to your local instance switch to your instance:

docker-machine ls
eval $(docker-machine env HOSTNAME_FROM_ABOVE)

Second, build the docker images. There are two, one is the Jenkins image itself, the other is an NGINX image which will be used to proxy access to Jenkins and perform SSL termination.

docker-compose build

If you run docker images you should see something like this:

$ docker images
REPOSITORY                   TAG                 IMAGE ID            CREATED             SIZE
dair-jenkins-guide_nginx     latest              b6554930ab8e        3 hours ago         111 MB
dair-jenkins-guide_jenkins   latest              d1dd6dd31ba6        4 hours ago         700 MB
docker.io/nginx              1.15.2              c82521676580        8 days ago          109 MB
docker.io/jenkins/jenkins    lts                 80fc01fa46f9        2 weeks ago         700 MB

The first two images are the ones that just got built, the other two are the images they're based on and are downloaded as part of the build process.

Now you can launch the containers:

docker-compose up -d

If you run docker ps you should see something like this:

$ docker ps
CONTAINER ID        IMAGE                        COMMAND                  CREATED             STATUS              PORTS                                         NAMES
811d7a26cffe        dair-jenkins-guide_nginx     "nginx -g 'daemon ..."   4 hours ago         Up 4 hours          0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp      nginx
4e88fe01ac10        dair-jenkins-guide_jenkins   "/sbin/tini -- /us..."   4 hours ago         Up 4 hours          8080/tcp, 0.0.0.0:5000->5000/tcp, 50000/tcp   jenkins

Now you should be able to access the Jenkins web interface in your browser at https://<floating_ip>. There should be a warning from your browser about an invalid certificate. Just ignore this and add an exception because NGINX is using a self-signed certificate. You should find yourself at this page:

Run this command to get the password:

docker-compose exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword

Next up is plugin installation:

If you're unsure which option to choose, pick the suggested plugins. You can always install and remove plugins after finishing the setup process.

When plugin installation is complete, fill in the details for the first admin user:

Finally, you need to set the Jenkins URL:

You should already be accessing Jenkins via the floating IP of the host that Docker Machine created so the default value will be correct.

Now you can login with the user account you created and start using Jenkins!

Configuration

Jenkins

Jenkins is incredibly configurable, even moreso when you consider that wide range of plugins available. If you're unfamiliar, we strongly recommend you start by taking a look at the documentation.

Almost all Jenkins configuration can be done through the web interface, however, if you need to manually edit something, or just want to poke around, running the following command will give you an interactive shell inside the container:

docker-compose exec jenkins bash

Any changes made under the /var/jenkins_home directory will be persisted even if the container is destroyed and re-created because it's actually a Docker-managed volume that is mounted inside the container.

Dependencies

If your build requires dependencies that aren't already in the Jenkins image you'll have to add them to the image. See jenkins/Dockerfile for instructions. Afterwards, rebuild the image and re-create the container:

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

Troubleshooting

If you run into any problems, you can look access the logs of each container with these commands:

docker-compose logs jenkins
docker-compose logs nginx

Replacing Self-Signed Certificate

When the nginx image is built a self signed cert is created to enable HTTPS, which is why you have to create an exception the first time you access Jenkins. If you have your own domain and certificate you can replace the self-signed after Nginx is already running with the following commands:

docker cp /path/to/cert nginx:/etc/nginx/ssl/server.crt
docker cp /path/to/key nginx:/etc/nginx/ssl/server.key
docker-compose restart nginx

The path /etc/nginx/ssl is mounted as data volume through Docker. This way even if the container is removed the certificate and key will still be in place when it's created again. If you ever want to remove the volume run this command:

docker volume rm dair-jenkins-guide_nginx-ssl

Upgrading

The Dockerfile used to build the Jenkins image uses the LTS release of Jenkins which can be out-of-date feature-wise. If you want to use a newer version, edit the first line of jenkins/Dockerfile and replace lts with either latest for the most recent version or a specific version like 2.135. Note that you do this at your own risk and this documentation may not be accurate for newer versions.

After modifying jenkins/Dockerfile you will need to rebuild the image and the jenkins container:

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