Public | Automated Build

Last pushed: 6 months ago
Short Description
Spin up a Jenkins container that can run Docker commands for the host.
Full Description

Outrigger Jenkins Docker

Spin up a Jenkins container that can run Docker commands for the host.

This image provides a Jenkins container meant to be used to run local jobs
including executing Docker commands on behalf of the host Docker system.
This allows Jenkins jobs to spin up and manage other Docker containers.

Additionally, it has a range of commonly useful Jenkins plugins which are tested
as working together and with the current Jenkins version.

For more documentation on how Outrigger images are constructed and how to work
with them, please see the documentation.

Usage Example

For consistency your Jenkins image should be defined in a docker-compose manifest
within the project structure. By convention we call this file jenkins.yml.
The entry might look like this:

# Container for running Jenkins with a local jobs volume
# Run this image via
#   - `docker-compose -f jenkins.yml run jenkins`
jenkins:
  image: outrigger/jenkins-docker
  volumes:
    # Primary jenkins configuration. Direct file mount prevents writing updates
    # from running instance.
    - ./env/jenkins/config.xml:/var/jenkins_home/config.xml
    # Mount the local project jobs into Jenkins
    - ./env/jenkins/jobs:/var/jenkins_home/jobs
    # Mount the docker socket so we can execute from within this container
    - /var/run/docker.sock:/var/run/docker.sock
    # Mount a stable location for the Jenkins workspace
    - /opt/development/example/jenkins/env/workspace:/opt/development/example/jenkins/env/workspace
    # Volume mount the private key
    - ~/.ssh/id_rsa:/root/.ssh/outrigger.key

Features

Private Key Import

When CI jobs have to deal with private repositories, Jenkins will need an
SSH key to connect to GitHub and BitBucket. Since our images are meant to be
public, we cannot build a private key into the image and we must import a key
into the running container.

Exported Job Configuration

The Jenkins container is customized mostly through volume mounts. Each project
repo should have their Jenkins CI jobs somewhere in the codebase. Typically
those get stored in env/jenkins/jobs and are mounted into the container into
the Jenkins Jobs directory with the following Volume specification

- ./env/jobs:/var/jenkins_home/jobs

Each time the Jenkins container is started up the job configuration will reset
back to what has been exported to the code. This creates stronger developer
ownership of job behavior, but can sometimes be confusing if deliberate changes
are made via the UI but not pulled back to code.

The XML configuration of any job can be viewed in the Jenkins UI via the config.xml
resource associated with each job, for example: http://jenkins.example.vm/job/ship-it/config.xml

Managing Docker Containers

In order for Jenkins to manage Docker containers, we volume mount the Docker
client tools and the Docker Socket from the host. This allows Jenkins to spawn
other peer containers outside of it's own container.

- /var/run/docker.sock:/var/run/docker.sock

The Jenkins image has the Docker engine and docker-compose installed, so you can
have a version mismatch between the Jenkins container and the version of Docker
running on the host.

Environment Variables

Outrigger images use Environment Variables and confd
to "templatize" a number of Docker environment configurations. These templates are
processed on startup with environment variables passed in via the docker run
command-line or via your docker-compose manifest file. Here are the "tunable"
configurations offered by this image.

Jenkins Docker has no templatized configuration at this time.

Customization

The most common need for customizing the Jenkins Docker container is to add
your own selection of Jenkins plugins. This will require your own customized
Dockerfile.

FROM outrigger/jenkins-docker

RUN install-versioned-plugins.sh \
        fun-plugin-one \
        funner-plugin-two:1.22 \
        the-funnest-plugin-of-all

If this is custom to a specific project, this might be placed in the
./env/jenkins directory from the usage example.

Once done, update your docker run or docker-compose jenkins.yml file as
follows:

jenkins:
-  image: outrigger/jenkins-docker
+  build: env/jenkins

Security Reports

Please email outrigger@phase2technology.com with security concerns.

Maintainers

Docker Pull Command
Owner
outrigger
Source Repository