Jenkins DSL ready

Goal: automate your Jenkins installation. Get Jenkins and its jobs ready with one docker command!

This Jenkins image is based on top of the official Jenkins image and as such provides all its features. Additionally, it comes with the Job DSL and Jenkins Configuration as Code plugins ready to use.

tl;dr

docker run -d -p 8080:8080 tomdesinto/jenkins-dsl-ready

docker run -d -p 8080:8080 -v /your/dsl/files/:/usr/share/jenkins/ref/jobs/SeedJob/workspace/:ro tomdesinto/jenkins-dsl-ready

docker run -d -p 8080:8080 -e SEEDJOB_GIT=https://your.repo.git tomdesinto/jenkins-dsl-ready

docker run -d -p 8080:8080 -e SEEDJOB_SVN=svn://your.repo tomdesinto/jenkins-dsl-ready

What does it do?

When you start the container the following happens:

1. All elements (plugins, jobs, config, etc) from /usr/share/jenkins/ref/ which are not yet in $JENKINS_HOME are copied over
2. Jenkins starts
3. all Groovy scripts found in $JENKINS_HOME/init.groovy.d/ are run, which includes our create-seed-job.groovy script
4. The SeedJob is eventually created and a run is scheduled if it was missing
5. The SeedJob, if run, creates additional jobs found in its workspace:

• by default the groovy scripts are provided by the docker image (see the dsl/ directory content)
• if a git repository url is provided with the SEEDJOB_GIT environment variable, the SeedJob will fetch the groovy scripts from there
• else if a svn repository url is provided with the SEEDJOB_SVN environment variable, the SeedJob will fetch the groovy scripts from there

Included plugins

• Job DSL
• Jenkins Configuration as Code (JCasC)
• Pipeline
• CloudBees Docker Pipeline
• Git
• Subversion (SVN)
• GitHub
• GitHub pull request builder
• Config File Provider
• Groovy PostBuild
• AnsiColor
• Rebuild
• Sidebar-Link
• Build-timeout
• Cobertura
• Copy Artifact
• Description Setter
• Email-ext
• Gradle
• Parameterized Trigger
• Publish Over Ssh
• Warnings Next Generation
• Workspace Cleanup

See the full list of plugins in the plugins.txt file.

Usage

Jenkins Configuration as Code (JCasC)

The Jenkins Configuration as Code Plugin provides an convenient way to configure Jenkins and some plugins from simple yaml files.

Provide those yaml files to the container with a volume mounted to the /var/jenkins_home/casc_configs/ directory:

docker run -d -p 8080:8080 -v /my/JCasC/jenkins.yml:/var/jenkins_home/casc_configs/jenkins.yml tomdesinto/jenkins-dsl-ready

Default DSL jobs

By running the image as follow:

docker run -d -p 8080:8080 tomdesinto/jenkins-dsl-ready

You will end up with an instance of Jenkins that demonstrates the usage of the DSL plugin. In this configuration you will have 2 default jobs created additionally to the SeedJob.

From there you can edit the SeedJob and make it fetch your DSL scripts from a SVN/git repository and make it create your other jobs.

Providing DSL jobs with Git/SVN

If you want to provide the DSL scripts from a remote repository, use either the SEEDJOB_GIT or SEEDJOB_SVN environment variables.

docker run -d -p 8080:8080 -e SEEDJOB_GIT=https://your.repo.git tomdesinto/jenkins-dsl-ready
docker run -d -p 8080:8080 -e SEEDJOB_SVN=svn://your.repo tomdesinto/jenkins-dsl-ready

Providing DSL jobs from a directory

You can provide you groovy DSL files from a directory on your docker host by mounting this directory with a docker volume on /usr/share/jenkins/ref/jobs/SeedJob/workspace/.

docker run -d -p 8080:8080 -v /somewhere/on/your/host/dsl/:/usr/share/jenkins/ref/jobs/SeedJob/workspace/:ro tomdesinto/jenkins-dsl-ready

Using Docker within jobs

Method 1 - Sharing the jenkins-dsl-ready Docker Host engine (root)

If you want your jobs to be able to make use of the Docker engine running on the Jenkins container host, first note that this is insecure as any Jenkins jobs will be able to take control of the full Docker engine (meaning even deleting any image/container on the Docker host), then you need to start the jenkins-dsl-ready container a bit differently:

• Jenkins must be run by the user root
• The /var/run/docker.sock socket file must be mounted as a volume

In the end, the command to run such a container is:

docker run -d \
    -u root \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -p 8080:8080 \
    --name jenkins \
    tomdesinto/jenkins-dsl-ready

From now on, you can call directly the docker command.

Method 2 - Sharing the jenkins-dsl-ready Docker Host engine (sudo)

Same as method 2, but we don't run Jenkins as root. In this case the Jenkins jobs will have to use sudo docker instead of just docker:

docker run -d \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -p 8080:8080 \
    --name jenkins \
    tomdesinto/jenkins-dsl-ready

In this setup, you can use docker with sudo: sudo docker.

Care should be given to files rights in Jenkins jobs. If a job makes use of sudo to run a command which will write files in the job workspace, those files will be owned by root. Jenkins would then be unable to manage then (wipe workspace, clear, etc) unless your job also makes sure to call chown jenkins on them.

Method 3 - Using dind (Docker in Docker)

Using the official docker:dind image, you can start a container which runs another child Docker engine which will be available to your jenkins-dsl-ready container through links. Be aware of constraints and pitfalls that comes with such a setup. Make sure to read Using Docker-in-Docker for your CI or testing environment? Think twice from Jérôme Petazzoni.

docker run -d --name dind \
    --privileged \
    -e DOCKER_DRIVER=overlay2 \
    -e DOCKER_TLS_CERTDIR='' \
    -e DOCKER_HOST=tcp://docker-daemon:2375 \
    docker:19.03-dind

note: use the tag that matches your docker version. i.e.: docker:1.8-dind if you have docker v1.8.1 or v1.8.2. docker:1.7-dind if you have docker v1.7.x, and so on. See available tags at https://hub.docker.com/r/library/docker/tags/

You would then start the jenkins-dsl-ready container with:

docker run -d \
    -p 8080:8080 \
    --link dind:dind \
    -e DOCKER_HOST=tcp://dind:2375 \
    --name jenkins \
    tomdesinto/jenkins-dsl-ready

From now on, you can call directly the docker command within Jenkins jobs.

Troubleshooting

If docker fails with error Error response from daemon: client is newer than server (client API version: 1.20, server API version: 1.19), or similar, then it means the version of the Docker client from the jenkins-dsl-ready image is newer than the Docker engine from the dind image. Refer to the note above to start a dind container having the right version of docker.

If docker fails with error docker: error while loading shared libraries: libapparmor.so.1: cannot open shared object file: No such file or directory, then you need to mount another volume on your container to enable the docker process to use the appArmor shared libraries. Depending on your system, the exact location of the librairies might differ from the following example: -v /usr/lib/x86_64-linux-gnu/libapparmor.so.1.1.0:/usr/lib/x86_64-linux-gnu/libapparmor.so.1. More info at https://github.com/SvenDowideit/dockerfiles/issues/17.

DSL syntax

Refer to the DSL Job reference. If you are just discovering the DSL Plugin, you should start with the tutorial.

Example of DSL script

Customizing the Docker image

You can build your own version of the Docker image to custimize it.

Add different default DSL files

You can add default DSL scripts to the dsl/ directory. When you build the docker image, those scripts will be copied to the SeedJob workspace when the container will be run.

Add more Jenkins plugins

Just edit the plugins.txt file. This file must contain one Jenkins plugin id per line. You can find the plugins' id on the official Jenkins plugins website.

For instance, to add the Green Balls plugin, add a line with greenballs.

You can pin a specific version for plugins with this syntax: greenballs:1.15

Add software and dependencies

Your jobs might depend on software which is not available in this image. You can build your own image with additional software by adding the commands to install them after the customize below section.

###############################################################################
##                          customize below                                  ##
###############################################################################

# Eventually place here any `apt-get install` command to add tools to the image
#


# COPY your Seed Job DSL script
COPY dsl/*.groovy /usr/share/jenkins/ref/jobs/SeedJob/workspace/