Customizing CloudBees Jenkins Distribution in Docker

3 minute read

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 script mentioned in this topic, some users have found that CloudBees Jenkins Distribution is unable to align plugin versions with the plugin envelope definition. This causes the "customize in Docker" feature not to work properly.

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, 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:

This is the only mechanism for customizing images currently supported by CloudBees Jenkins Distribution.

Creating the plugin.txt file

The 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.txt file:

  1. Create the plugins.txt file in a local directory.

  2. 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:

    plugin version in header callout
  3. Add the plugin to the plugins.txt file as a single line containing the plugin identifier and its version, separated by a colon:

  4. For more information about the syntax of plugins.txt, see the plugin version format section of the Docker documentation.

  5. After creating plugins.txt, move on to Creating the Dockerfile.

Creating the Dockerfile

The customized Dockerfile specifies how you want to extend the CloudBees Jenkins Distribution base image. It executes the script from the CloudBees Jenkins Distribution base image (located in /usr/local/bin) in combination with the contents of your plugins.txt file.

To create the Dockerfile:

  1. In the same directory as the one in which you created your plugins.txt file, create a file called Dockerfile.

  2. 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/ < /usr/share/cloudbees-jenkins-distribution/ref/plugins.txt
    1. The FROM instruction specifies the CloudBees Jenkins Distribution base image.

    2. The COPY instruction copies the plugins.txt file that you previously created into the container’s /usr/share/cloudbees-jenkins-distribution/ref/ directory.

    3. The RUN instruction executes the /usr/local/bin/ script, using the contents of the plugins.txt file as its argument.

  3. Save the Dockerfile.

Extending the CloudBees Jenkins Distribution Docker image

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 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:

  1. In the same directory as plugins.txt and the Dockerfile, run the command:

    $ docker image build --name . (1)

    Be sure to use an identifiable name and tag for your image, so that you can easily identify it later.

  2. The command creates a Docker image named with the tag 1.0. The image contains both the pre-packaged plugins from CloudBees Jenkins Distribution and the plugins listed in the plugins.txt file.

  3. 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.