Using CloudBees Jenkins Distribution with Docker

The easiest way to install and run CloudBees Jenkins Distribution is with the supported
Docker container, which bundles the necessary Java
runtime environment and other defaults into the container.

What is Docker

Docker is a platform for
running applications in an isolated environment called a
container (or Docker container). Applications like the CloudBees Jenkins Distribution can be downloaded
as read-only images (or Docker images), each of which is run in Docker as a container.
A Docker container is in effect a running instance of a Docker image. From this perspective,
an image is stored permanently more or less (i.e., insofar as image updates are published),
whereas containers are stored temporarily. Read more about these concepts in the Docker
documentation’s Getting Started.

Docker’s fundamental platform and container design means that a single Docker image for any given application (like CloudBees Jenkins Distribution) can be run on any operating system or cloud service that is also running Docker.

Installing using Docker

This procedure assumes the destination machine has a running Docker daemon available to
the administrator.

Ensure you configure Docker so it can be managed as a non-root user in Linux. Read more
about this in Docker’s Post-installation steps for Linux
page of their documentation. This page also contains information about how to configure
Docker to start on boot.

The annotated options in this docker run …​ command above are explained as
follows (note that a copyable version of this command is available
below):

( Optional ) Automatically removes the Docker container (which is the
instantiation of the cloudbees/cloudbees-jenkins-distribution image below) when it is shut down. This
keeps your Docker environment tidy if you need to quit CloudBees Jenkins Distribution.

( Optional ) Runs the cloudbees/cloudbees-jenkins-distribution container in the background
(i.e. "detached" mode) and outputs the container ID. If you do not specify this
option, then the running Docker log for this container is output in the terminal
window.

Maps (i.e. "publishes") port 8080 of the cloudbees/cloudbees-jenkins-distribution container to
port 8080 on the host machine. The first number represents the port on the host
while the last represents the container’s port. Therefore, if you specify
-p 49000:8080 for this option, you would access CloudBees Jenkins Distribution on your host machine
through port 49000.

( Optional ) Maps port 50000 of the cloudbees/cloudbees-jenkins-distribution container to port
50000 on the host machine. This is only necessary if you have set up one or more
JNLP-based Jenkins agents on other machines to interact with the
cloudbees/cloudbees-jenkins-distribution container. JNLP-based agents communicate with
CloudBees Jenkins Distribution through TCP port 50000 by default. You can change this port number on
your CloudBees Jenkins Distribution instance through the Manage Jenkins > Configure Global Security
page. If you were to change CloudBees Jenkins Distribution’s TCP port for JNLP agents value to 51000
(for example), then you would need to re-run CloudBees Jenkins Distribution (via this docker run …​
command) and specify this "publish" option with something like -p 52000:51000,
where the last value matches this changed value on CloudBees Jenkins Distribution and the first value is
the port number on the CloudBees Jenkins Distribution’s host machine through which the JNLP-based agents
communicate (to CloudBees Jenkins Distribution) - i.e. 52000.

( Optional but highly recommended ) Maps the /var/jenkins_home directory
in the container to the Docker
volume with the name
jenkins-data. If this volume does not exist, then this docker run command
will automatically create the volume for you. This option is required if you
want your Jenkins state to persist each time you restart Jenkins (via this
docker run …​ command). If you do not specify this option, then Jenkins will
effectively reset to a new instance after each restart.

Notes:
The jenkins-data volume can be created independently using the
docker volume create
command: docker volume create jenkins-data. Also, instead of mapping the
/var/jenkins_home directory to a Docker volume, you can map this directory
to one on your host machine’s file system. For example, specifying the option
-v $HOME/jenkins:/var/jenkins_home maps the container’s /var/jenkins_home
directory to the jenkins subdirectory within the $HOME directory on your
host machine, which typically is /home/<your-username>/jenkins.

( Optional ) /var/run/docker.sock represents the Unix-based socket on
which the Docker daemon listens. This mapping allows the cloudbees/cloudbees-jenkins-distribution
container to communicate with the Docker daemon, which is required if the
cloudbees/cloudbees-jenkins-distribution container needs to instantiate other Docker containers. This
option is necessary if you run declarative Pipelines whose syntax contains the
agent section with
the docker parameter - i.e. agent { docker { …​ } }. Read more about this
on the Pipeline Syntax page
of the {JOSS} User Documentation.

The cloudbees/cloudbees-jenkins-distribution Docker image itself. If this image has not already
been downloaded, then this docker run command automatically downloads the
image for you. Furthermore, if any updates to this image were published since
you last ran this command, then running this command again automatically
downloads these published image updates.

The registered trademark Jenkins® is used pursuant to a sublicense from the Jenkins project and Software in the Public Interest, Inc. Read more at
www.cloudbees.com/jenkins/about.

Apache, Apache Ant, Apache Maven, Ant and Maven are trademarks of
The Apache Software Foundation. Used with permission. No endorsement by
The Apache Software Foundation is implied by the use of these marks.

Other names may be trademarks of their respective owners.
Many of the designations used by manufacturers and sellers
to distinguish their products are claimed as trademarks. Where those
designations appear in this book, and CloudBees was aware
of a trademark claim, the designations have been printed in caps or initial
caps.

While every precaution has been taken in the preparation of this book,
the publisher and authors assume no responsibility for errors or omissions,
or for damages resulting from the use of the information contained
herein.