Customizing CloudBees Jenkins Distribution in Docker
CloudBees no longer supports CloudBees Jenkins Distribution as of February 24, 2021. Please refer to the following step-by-step documentation for Migrating from CloudBees Jenkins Distribution to Jenkins LTS. The increased alignment between CloudBees Jenkins Distribution and Jenkins means users will experience zero impact to Pipeline execution. Existing customers can also contact CloudBees Support to help ensure a smooth transition.
Please see About the CloudBees Jenkins Distribution retirement for more information.
This feature is affected by a known issue.
Under some circumstances, after running the
The normal functions of CloudBees Jenkins Distribution are unaffected by this issue: only the "customize CloudBees Jenkins Distribution in Docker" feature is affected.
Starting with CloudBees Jenkins Distribution version 220.127.116.11, you can customize the pre-installed plugins within your CloudBees Jenkins Distribution Docker image.
This customization is useful when creating new instances of CloudBees Jenkins Distribution, especially when combined with Configuration as Code.
To customize which plugins are pre-installed in the CloudBees Jenkins Distribution image, you will need to create two files:
And use the Dockerfile to extend the base CloudBees Jenkins Distribution image.
|This is the only mechanism for customizing images currently supported by CloudBees Jenkins Distribution.|
plugins.txt file should contain a list of plugins you want to pre-install on your custom CloudBees Jenkins Distribution Docker image.
To create the
plugins.txtfile in a local directory.
Obtain the plugin’s version and identifier from the CloudBees plugin site, with the plugin’s ID (1) and version (2) in the header. For example, the Badge plugin:
Add the plugin to the
plugins.txtfile as a single line containing the plugin identifier and its version, separated by a colon:
For more information about the syntax of
plugins.txt, see the plugin version format section of the Docker documentation.
plugins.txt, move on to Creating the Dockerfile.
The customized Dockerfile specifies how you want to extend the CloudBees Jenkins Distribution base image. It executes the
install.sh script from the CloudBees Jenkins Distribution base image (located in
/usr/local/bin) in combination with the contents of your
To create the Dockerfile:
In the same directory as the one in which you created your
plugins.txtfile, create a file called
Populate the Dockerfile file with the following contents:
FROM cloudbees/cloudbees-jenkins-distribution COPY plugins.txt /usr/share/cloudbees-jenkins-distribution/ref/plugins.txt RUN /usr/local/bin/install-plugins.sh < /usr/share/cloudbees-jenkins-distribution/ref/plugins.txt
The FROM instruction specifies the CloudBees Jenkins Distribution base image.
COPYinstruction copies the
plugins.txtfile that you previously created into the container’s
RUNinstruction executes the
/usr/local/bin/install-plugins.shscript, using the contents of the
plugins.txtfile as its argument.
Save the Dockerfile.
You will extend the CloudBees Jenkins Distribution Docker image by starting a Docker build, which will invoke the
Dockerfile you just created. When Docker executes the
install-plugin.sh script, it will downloads the plugins listed in the
plugins.txt file and resolve their dependencies.
If there are any missing plugin dependencies (whether they haven’t been installed, or they’re not explicitly listed in
plugins.txt), those plugins will be downloaded and installed.
To create a Docker image using your specified plugins:
In the same directory as
Dockerfile, run the command:
$ docker image build --name example.com/custom-cloudbees-jenkins-distribution:1.0 . (1)
Be sure to use an identifiable name and tag for your image, so that you can easily identify it later.
The command creates a Docker image named
example.com/custom-cloudbees-jenkins-distributionwith the tag
1.0. The image contains both the pre-packaged plugins from CloudBees Jenkins Distribution and the plugins listed in the
After you have created the new image, you can start a new container using the image, which will create a customized instance of CloudBees Jenkins Distribution. For more information on running CloudBees Jenkins Distribution in Docker, see Installing and using CloudBees Jenkins Distribution with Docker.