Install client controllers

The following installation instructions describe how to install a client controller on your chosen hardware or virtual machine and the requirements for a client controller installation.

Client controllers are available as a standalone multi-platform WAR file or as an installation package for the following operating systems:

Linux
Windows

A client controller can also be run directly on the operating system (using the WAR file) or on one of the following platforms:

Docker
Apache Tomcat (WAR file)

CloudBees support for client controller installations:

CloudBees provides support for the following client controller installation scenarios:
- Client controllers installed using operating system-specific package management tools or installers on an operating system mentioned above. The operating system may be installed:
  - natively on hardware or
  - virtually in a virtual machine environment.
- Running client controllers in Docker, which in turn is running on a Linux kernel (i.e. Linux operating systems).
- Direct WAR file deployments/installations on an operating system mentioned above.
CloudBees does not provide support for the following client controller installation scenarios:
- Attempting to install or run client controllers on mobile devices or mobile device operating systems.
- Installing or running client controllers on operating systems that are no longer supported by the organizations who develop the operating system - e.g. Windows XP.

Read more about CloudBees support for CloudBees CI on traditional platforms in: Support Lifecycle and Update Policies for CloudBees CI on traditional platforms.

About client controller releases

CloudBees CI on traditional platforms and its components are based on the Long Term Support (LTS) releases of Jenkins. A "refresh" build is released every time the Jenkins community performs a LTS release, which is typically every 3 months.

The downloadable artifacts are named as 2.x.y.z where 2.x.y is a Jenkins LTS based on the 2.x weekly release and z is a CloudBees CI build number. This z digit allows an existing CloudBees CI package to perform an "in-place" installation of files (during upgrades) without the need to uninstall CloudBees CI packages first.

See the CloudBees CI release notes page to access the release notes for CloudBees CI.

Installing on Linux

The instructions in this section provide details on how to install a client controller on Linux and run it as a service directly on a JVM.

The CloudBees CI on traditional platforms RPM installation package requires systemd. The majority of Linux distributions have adopted systemd, but if you attempt to use the RPM package to install CloudBees CI on traditional platforms on a Linux distribution that does not support systemd, the installation will appear to be successful, however the service will not be able to start.

To run a client controller on another platform such as Docker or Apache Tomcat on Linux, see the relevant instructions below.

Installing on Ubuntu or Debian

On Debian-based Linux distributions such as Ubuntu, a client controller can be installed using the Apt package management tools.

Ensure that you have met the appropriate hardware and software requirements.
Ensure that you have met all the JVM requirements.

Add the Apt key of the Debian package repository for the client controller application to your operating system with this command:

wget -q -O - https://downloads.cloudbees.com/cloudbees-core/traditional/operations-center/rolling/debian/cloudbees.com.key | sudo tee /etc/apt/trusted.gpg.d/cloudbees.com.asc▼

Add the following entry to Apt’s "sources" list file (/etc/apt/sources.list.d/cloudbees.list):

deb https://downloads.cloudbees.com/cloudbees-core/traditional/client-master/rolling/debian binary/▼

Update your local Apt package list with this command:
```
sudo apt-get update▼
```
Install the client controller application:
```
sudo apt-get install cloudbees-core-cm▼
```
Once the installation process is completed, the client controller automatically starts running and by default, is accessible on port 8080.

To access the client controller, open your favorite browser and enter the URL: http://client-controller-url:8080/.

For details about stopping and (re-)starting the client controller, see Stopping and (re-)starting the service on Linux.

The log file is located at /var/log/cloudbees-core-cm/cloudbees-core-cm.log.
Refer to the Ubuntu and Debian instructions in the Jenkins Handbook for more information.

Installing on Red Hat, CentOS, Fedora or Amazon Linux 2

A client controller can be installed on distributions such as Red Hat, CentOS, Fedora and Amazon Linux 2 using either the Yum package manager or the DNF package manager.

Ensure that you have met the appropriate hardware and software requirements.

The epel-release package is required to install CloudBees CI on traditional platforms using an RPM, however some CentOS distributions do not install the package by default. For those CentOS distributions, run the following command before you begin the installation procedure:

sudo yum install epel-release▼

Ensure that you have met all the JVM requirements.
Add the package manager repository for the client controller application to your operating system with this command:
```
sudo wget -O /etc/yum.repos.d/cloudbees-core-cm.repo https://downloads.cloudbees.com/cloudbees-core/traditional/client-master/rolling/rpm/cloudbees-core-cm.repo▼
```
This repository is used to automate the installation and upgrade of the client controller application on your operating system.
Add the key of this repository to your operating system:
```
sudo rpm --import https://downloads.cloudbees.com/cloudbees-core/traditional/client-master/rolling/rpm/cloudbees.com.key▼
```
This command may fail if you previously imported the key and already have it added to your operating system. In such cases, ignore the error.
Before installing the client controller, update your operating system’s software with this command (if you are using Yum):
```
sudo yum update▼
```
If you are using DNF, use this command instead:
```
sudo dnf upgrade▼
```
Install the client controller application; the Yum command is:
```
sudo yum install cloudbees-core-cm▼
```
The DNF command is:
```
sudo dnf install cloudbees-core-cm▼
```
Once the installation process is completed, the client controller automatically starts running and by default, is accessible on port 8080.

To access the client controller, open your favorite browser and access the URL: http://client-controller-url:8080/.

For details about stopping and (re-)starting the client controller, see Stopping and (re-)starting the service on Linux.

The log file is located at /var/log/cloudbees-core-cm/cloudbees-core-cm.log.
Refer to the Ubuntu and Debian instructions in the Jenkins Wiki for more information.

Installing on OpenSUSE

On OpenSUSE, a client controller can be installed using the Zypper package manager.

Ensure that you have met the appropriate hardware and software requirements and that your operating
Ensure that you have met all the JVM requirements.
Add the package manager repository for the client controller application to your operating system either with this command:
```
sudo zypper addrepo -f https://downloads.cloudbees.com/cloudbees-core/traditional/client-master/rolling/opensuse/ cloudbees-core-cm▼
```
This repository is used to automate the installation and upgrade of the client controller application on your operating system.
Install the client controller application:
```
sudo zypper install cloudbees-core-cm▼
```
Once the installation process is completed, the client controller automatically starts running and by default, is accessible on port 8080.

To access the client controller, open your favorite browser and access the URL: http://client-controller-url:8080/.

Stopping and (re-)starting the service on Linux

To stop a client controller instance, execute this command:

sudo service cloudbees-core-cm stop▼

To (re-)start the client controller instance, execute this command:

sudo service cloudbees-core-cm start▼

Installing on Microsoft Windows

The instructions in this section provide details on how to install a client controller on Microsoft Windows, which is configured as a Windows service that runs upon Windows startup.

The client controller Windows installer requires a 64-bit Windows operating system and a compatible .NET Framework (2.0, 3.5.1, 4.0) in order to be installed as a Windows service. Most Windows versions are configured with a compatible .NET Framework by default. Windows 7 includes the .NET Framework 3.5.1, although this may not be installed or configured by default; you must ensure this .NET Framework is installed/configured before running the client controller installer. Read more about installing .NET Frameworks on Windows 7 on the Microsoft Docs and TechHit sites.

To install the client controller on Windows:

Ensure that you have met the appropriate hardware requirements and that your operating system has met the JVM requirements above.
Download the Windows installer file (i.e. a Zip archived MSI file) ^[1] for the client controller from this web site’s downloads page.

Other versions of the client controller Windows installer file can be obtained from the client controller Windows installer downloads page.
Execute the installer (MSI) file by double-clicking it or run the msiexec.exe command (at the command prompt) if you need to specify other options.

Once the installation process is completed, it automatically starts running the client controller, which by default is accessible through port 8080.

To access the client controller, open your favorite browser and access the URL: http://client-controller-url:8080/.

Running the WAR file directly

A client controller can be run directly on a JVM, which in turn is running on any of the supported operating systems using the client controller WAR file.

The client controller WAR file is multi-platform and runs on the JVMs of other operating systems such as macOS. However, CloudBees does not support running the client controller WAR on operating systems other than those listed in Supported platforms.

To run the client controller directly on your operating system JVM:

Ensure that you have met the appropriate hardware requirements and that your operating system has met the JVM requirements.
Download the Java WAR file for the client controller (named cloudbees-core-cm.war) from this website’s downloads page and move it to an appropriate directory on your operating system’s file system.

Other versions of the client controller Java WAR file can be obtained from the client controller WAR file downloads page.
In a terminal/command prompt (window), cd to the directory containing the client controller WAR file
(cloudbees-core-cm.war).
Start the client controller with this command:
```
java -jar cloudbees-core-cm.war▼
```
By default, the client controller is accessible through port 8080.

To access the client controller, open your favorite browser and access the URL: http://client-master-url:8080/.

Note:

You can change the port by specifying the --httpPort option when running the java -jar cloudbees-core-cm.war command. For example, to make the client controller accessible through port 9090, start the client controller using the command: java -jar cloudbees-core-cm.war --httpPort=9090

Running in Docker

Docker is a platform for running applications in an isolated environment called a "container" (or Docker container). Applications like the client controller 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, Part 1: Orientation and setup page.

Docker’s fundamental platform and container design means that a single Docker image for any given application (like the client controller) can be run on any operating system or cloud service that is also running Docker. However, CloudBees only supports running a client controller on Docker when Docker is running on a Linux operating system.

Install Docker

To install Docker on your operating system, visit the Docker store website and click the Docker Community Edition … box that is suitable for your Linux operating system. Follow the installation instructions on their website.

A client controller can run on Docker Community Edition (abbreviated to Docker CE) or on Docker Enterprise Edition, which you can access through Docker EE on this Docker store page.

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.

Download and run the client controller in Docker

Complete the following steps to download and run the client controller in Docker.

You can optionally verify the CloudBees CI on traditional platforms Docker images to ensure their origin and authenticity.

Ensure that you have met the appropriate hardware requirements. (There are no JVM requirements for the host machine to run a client controller in Docker.)

Download the Docker image for the client controller and run it as a container in Docker using the following
docker run command:

docker run \
  --rm \ (1)
  -d \ (2)
  -p 8080:8080 \ (3)
  -p 50000:50000 \ (4)
  -v jenkins-data:/var/jenkins_home \ (5)
  cloudbees/cloudbees-core-cm (6)▼

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-core-cm image below) when it is shut down. This keeps your Docker environment tidy if you need to quit the client controller.

2 ( Optional ) Runs the cloudbees/cloudbees-core-cm 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-core-cm 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 the client controller on your host machine through port 49000.

4 ( Optional ) Maps port 50000 of the cloudbees/cloudbees-core-cm 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-core-cm (client controller) container. JNLP-based agents communicate with the client controller through TCP port 50000 by default. You can change this port number on your client controller through the Manage Jenkins > Configure Global Security page. If you were to change your client controller’s TCP port for JNLP agents value to 51000 (for example), then you would need to re-run the client controller (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 the client controller and the first value is the port number on the client controller’s host machine through which the JNLP-based agents communicate (to the client controller) - 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.

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

The cloudbees/cloudbees-core-cm 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-core-cm. This Docker image is also accessible from the cloudbees/cloudbees-core-cm image (from the Docker Hub repository).

To copy and paste the command snippet above, use this annotation-free version here:

docker run \
  --rm \
  -d \
  -p 8080:8080 \
  -p 50000:50000 \
  -v jenkins-data:/var/jenkins_home \
  cloudbees/cloudbees-core-cm▼

Running in Apache Tomcat

End-of-life announcement

If you run CloudBees CI in Apache Tomcat, it was deprecated and CloudBees CI’s support ends after October 2025. An Administrative Monitor was added to advise customers on how to migrate from Tomcat to a CloudBees Linux package. For more information about the migration, refer to Migrate CloudBees CI on traditional platforms from Tomcat to a CloudBees Linux package.

Please contact CloudBees Support if you have any concerns or questions.

A client controller can be run on Apache Tomcat version 8.5, using the client controller WAR file.

Ensure that you have met the appropriate hardware requirements and that Apache Tomcat 8.5 has been installed on your host machine. Read more about this in the Tomcat Setup instructions of the Apache Tomcat 8.5 documentation.
Download the Java WAR file for the client controller (named cloudbees-core-cm.war) from this website’s downloads page.

Other versions of the client controller Java WAR file can be obtained from the client controller WAR file downloads page.
Deploy the client controller WAR file into Tomcat. Read more about this in the Tomcat Web Application Deployment instructions in the Apache Tomcat 8.5 documentation.

Important notes:

The simplest way to deploy the client controller into Tomcat is to:
1. Copy the client controller WAR file (cloudbees-core-cm.war) to the $CATALINA_BASE/webapps or $CATALINA_HOME/webapps directory.
2. Start Tomcat.
3. Access the client controller through the URL: http://tomcat-url:port-number/cloudbees-core-cm.
To run Tomcat to host the client controller only:
1. Remove everything from the $CATALINA_BASE/webapps or $CATALINA_HOME/webapps directory.
2. Copy the client controller WAR file (cloudbees-core-cm.war) to this directory.
3. Start Tomcat.
4. Access the client controller through the URL: http://tomcat-url:port-number.
Ensure the org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH system property has been set to true, which allows encoded slashes (for example, %2F and %5C for forward and backslashes) as path delimiters. If you do not set this property, the client controller is likely to report the warning: It appears that your reverse proxy set up is broken.
Read more about this system property and others in the System Properties section of the Apache Tomcat 8 Configuration Reference. You can set this property before starting Tomcat by either:
- Setting $CATALINA_OPTS with the value:
  -Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true. or
- Adding the following to the catalina.properties file:
  org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true.
To set the $JENKINS_HOME directory, do one of the following before starting Tomcat:
- Setting $CATALINA_OPTS with the value: -DJENKINS_HOME=/path/to/jenkins_home/.
- Setting $JENKINS_HOME with its path value - for example: export $JENKINS_HOME=/path/to/jenkins_home/ (before running the command to start Tomcat).
A client controller and operations center server cannot be hosted on the same JVM.

In August 2020, the Jenkins project voted to replace the term master with controller. We have taken a pragmatic approach to cleaning these up, ensuring the least amount of downstream impact as possible. CloudBees is committed to ensuring a culture and environment of inclusiveness and acceptance - this includes ensuring the changes are not just cosmetic ones, but pervasive. As this change happens, please note that the term master has been replaced through the latest versions of the CloudBees documentation with controller (as in managed controller, client controller, team controller) except when still used in the UI or in code.