Introduction
What’s new
Introduction
Docker
Linux
Microsoft Windows
WAR file
Kubernetes
Post-install configuration
Introduction
Configuration as code
Customizing CloudBees Jenkins Distribution in Docker
Authenticating to CloudBees Jenkins Distribution using GitHub App authentication
Creating projects based on GitHub repository structure
Introduction
Understanding Beekeeper security warnings
Extended security settings
Preventing unauthorized interaction between builds
Data collection for the CloudBees Analytics Plugin
Generating a support bundle
Backup and restore
Jenkins CLI tool
About plugins
IntroductionRestart Aborted Builds pluginAWS CLI pluginCloudBees Amazon Web Services Deploy EngineMicrosoft Azure CLI pluginCloudBees Backup pluginCloudBees Bitbucket Branch Source pluginCloudBees Assurance ProgramCloudBees CasC API pluginCloudBees CasC Client pluginCloudBees CasC Items API pluginCloudBees CasC Items Commons pluginCloudBees CasC Items Controller pluginCloudBees CasC Items Server pluginCloudBees CasC Server pluginCloud Foundry CLI pluginConsolidated Build View pluginCloudBees Docker Build and Publish pluginCloudBees Docker TraceabilityDocker Pipeline pluginCloudBees Docker Hub/Registry NotificationCloudBees Even Scheduler pluginCloudBees Fast Archiving pluginFolders pluginFolders Plus pluginGitHub Branch Source pluginCloudBees Inactive Items pluginJenkins Health Advisor by CloudBeesCloudBees Long-Running Build pluginMonitoring pluginNodes Plus pluginOpenShift CLI pluginCloudBees Plugin Usage Analyzer pluginCloudBees Prometheus Metrics pluginPull Request Builder for GitHub pluginCloudBees Quiet Start pluginSecure Copy pluginSkip Next Build pluginSSH Build Agents pluginCloudBees Support pluginTemplate pluginCloudBees Label Throttling pluginUser Activity MonitoringCloudBees Git Validated Merge pluginVisual Studio Team Services pluginWikitext Security plugin
Plugin management
IntroductionGetting started with plugin managementCloudBees Assurance ProgramBeekeeper Upgrade AssistantAdding Beekeeper plugin exceptionsFinding the support tier for a pluginInstalling pluginsUpgrading plugins from the Plugin ManagerUninstalling pluginsDisabling pluginsReviewing plugin usageConfiguring plugin catalogsManaging plugins with Update CenterManaging plugins in a secure environment
Getting started
IntroductionPipeline termsPipeline project typesCloudBees Pipeline benefits
Planning for Pipelines
IntroductionUsing Pipeline development utilitiesDetermining plugin compatibilityPipeline best practices
Creating Pipelines
IntroductionPrerequisitesCreating your first PipelineCreating Pipelines in SCMCreating Pipelines in Web UIUsing Pipeline as Code
Automating with Jenkinsfile
IntroductionConfig Adv ScriptedConfig Build StageConfig Deploy StageConfig Optional Step ArgsConfig Test StageCreating JenkinsfileCustomizing ParametersHandling FailuresString InterpolationUsing Multiple AgentsWorking With The Env
Administering Pipelines
IntroductionControlling buildsManaging artifactsTracing artifactsTriggering jobs with a simple webhookRestoring filesVisualizing PipelineInserting checkpointsSecuring PipelinesConfiguring Pipelines with user-scoped credentialsUsing Pipeline PoliciesSpecifying a matrix of one or more dimensionsConverting a Freestyle project to a Declarative Pipeline
Remote collaboration features
IntroductionTrigger a job with a notification event using Cross Team CollaborationEnable external notification events with external HTTP endpointsCluster-wide copy artifactsCluster-wide job triggers
Pipeline templates
IntroductionSetting up a Pipeline Template CatalogDefining Pipeline Template CatalogsSetting Up A Pipeline TemplateUsing parameters in template.yamlManaging multibranch Pipeline options in template.yamlManaging Pipeline Template Catalogs in bulkExample full Maven/Java app Jenkinsfile
Pipeline syntax reference
IntroductionUsing Declarative Pipeline syntaxUsing Scripted Pipeline syntax
Multibranch Pipeline Template syntax
IntroductionBranch SourceBitbucketGitHubGitBranch Property StrategyExamples
CloudBees Jenkins JVM troubleshooting
Performance decision tree for troubleshooting
Troubleshooting memory leaks
Troubleshooting file and thread leaks
Migrating from CloudBees Jenkins Team to CloudBees Jenkins Distribution
Migrating from Jenkins LTS to CloudBees Jenkins Distribution
Migrating from CloudBees Jenkins Distribution to Jenkins LTS
Support policies
License report

Installing and using CloudBees Jenkins Distribution with Docker

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

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.

To verify that Docker is available:

docker info

If Docker has not already been installed, consult the Docker Engine installation guide for more information.

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.

Using the Docker image

Once Docker is up and running, the cloudbees/cloudbees-jenkins-distribution image can be pulled and run.

  1. Download the docker image for CloudBees Jenkins Distribution.

    docker pull cloudbees/cloudbees-jenkins-distribution

Running CloudBees Jenkins Distribution in Docker

Run the image for CloudBees Jenkins Distribution as a container in Docker using the docker run command.

If you are using a CloudBees Jenkins Distribution prior to 2.176.2.3, use /var/jenkins_home as the volume instead of /var/cloudbees-jenkins-distribution. For example, -v jenkins-data:/var/jenkins_home \ instead of -v jenkins-data:/var/cloudbees-jenkins-distribution \.

You can use either a basic command or with more specific options.

The basic command is:

docker run cloudbees/cloudbees-jenkins-distribution

The docker run example below provides specific options and explanations.

docker run \
  -u root \
  --rm \ (1)
  -d \ (2)
  -p 8080:8080 \ (3)
  -p 50000:50000 \ (4)
  -v jenkins-data:/var/cloudbees-jenkins-distribution \ (5)
  -v /var/run/docker.sock:/var/run/docker.sock \ (6)
  cloudbees/cloudbees-jenkins-distribution (7)

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

1 ( 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.
2 ( 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.
3 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.
4 ( 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.
5 ( Optional but highly recommended ) Maps the /var/cloudbees-jenkins-distribution 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.

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.

On versions prior to 2.176.2.3 you need to use /var/jenkins_home instead of /var-cloudbees-jenkins-distribution
6 ( 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 Jenkins User Documentation.
7 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.

This Docker image can be downloaded (or updated) independently using the docker pull command: docker pull cloudbees/cloudbees-jenkins-distribution. This Docker image is also accessible from the cloudbees/cloudbees-jenkins-distribution image (from the Docker Hub repository).

To copy and paste the command snippet above, use this annotation-free version here: 
docker run \
  -u root \
  --rm \
  -d \
  -p 8080:8080 \
  -p 50000:50000 \
  -v jenkins-data:/var/cloudbees-jenkins-distribution \
  -v /var/run/docker.sock:/var/run/docker.sock \
  cloudbees/cloudbees-jenkins-distribution

After the process has completed, CloudBees Jenkins Distribution service should start automatically and be available in a web browser at localhost:8080 by default.

After installation, the Getting Started wizard will walk you through installing a curated set of plugins and creating the first admin account.

Security and unlocking the distribution

CloudBees Jenkins Distribution is initially configured to be secure on first launch. During installation, a password is generated and saved in a local file called initialAdminPassword. The file location depends upon the operating system you are using.

This password is required to unlock the instance on the Unlock Jenkins page.

To locate the password:

  1. Open a browser to http://localhost:8080.

  2. Open the initialAdminPassword file using the location displayed on the Unlock Jenkins page.

  3. Copy the password from the file.

Alternatively, the password may be displayed during installation. For example, the output below was from installing on macOS using a WAR file:

*************************************************************
*************************************************************
*************************************************************

Jenkins initial setup is required. An admin user has been created and a password generated.
Please use the following password to proceed to installation:

d661ea28c6b94406ad627601b6f4aa877

This may also be found at: /Users/<username>/.jenkins/secrets/initialAdminPassword

*************************************************************
*************************************************************
*************************************************************

Registration

During setup, you will be prompted to choose a registration type. You can register with a free product key online or contact CloudBees Support to obtain registration activation.

Using the Getting Started wizard

  1. Open a browser to http://localhost:8080.

  2. On the Unlock Jenkins page, paste in the Administrator password retrieved in the previous section in the field. Press Continue.

  3. Select the appropriate registration option on the License page.

    • Activate CloudBees Jenkins Distribution (requires online activation): Complete the form on Register CloudBees Jenkins Distribution page. Enter your name, email and company, check the box to accept the license agreement and click Submit. The Setup Wizard will contact CloudBees to create a license and apply the license to the product.

    • Use a license key (Apply a valid license key; useful for offline installations): Click Activate CloudBees Jenkins Distribution to obtain a free license (requires internet access). If necessary, contact CloudBees Sales to obtain your existing product registration. Select license key and paste the License Key and License Certificate from your existing registration into the appropriate fields. Review the license and then accept the license by clicking the check box and click Submit.

  4. Select Install suggested plugins on the Customize Jenkins page to install the curated set of plugins recommended by CloudBees.

  5. The Getting Started page displays the setup progress. If any updates are available, you will also be given the option to upgrade. These upgrades may also be performed at a later time using the Beekeeper Upgrade Assistant.

  6. On the Create First Admin User page, enter a username, password (twice), full name, and email address for the first admin user. Press Save and Continue.

  7. Enter a new value for the Jenkins URL on the Instance Configuration page. You may choose to use the default value or to enter a new URL. Press Save and Finish.

    The Jenkins URL provides the root URL for absolute links to various Jenkins resources, including email notifications, PR status updates, and the BUILD_URL environment variable provided to build steps.

  8. You may be asked to reboot your system.

Introduction
Linux