Installing the operations center

The installation instructions in this chapter describes how to install an operations center on your chosen hardware or virtual machine and the requirements for an operations center installation.

The operations center is available as a standalone multi-platform WAR file or as an installation package for the following operating systems:

Linux
- Ubuntu
- Red Hat
- Debian
- CentOS
- Fedora
- Amazon Linux 2
- OpenSUSE
Windows

The operations center 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)

Notes: CloudBees support for operations center installations:

CloudBees provides support for the following operations center installation scenarios:
- Operations center 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 operations center 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 operations center installation scenarios:
- Attempting to install or run operations center on mobile devices or mobile device operating systems.
- Installing or running operations center 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 operations center 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 operations center 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 the operations center 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, the operations center 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 operations center 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/operations-center/rolling/debian binary/▼

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

To access the operations center, open your favorite browser and enter the URL: http://operations-center-url:8888/.

For details about stopping and re-starting the operations center, refer to Stopping and (re-)starting the service on Linux.

The log file is located at /var/log/cloudbees-core-oc/cloudbees-core-oc.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

The operations center 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 operations center application to your operating system with this command:
```
sudo wget -O /etc/yum.repos.d/cloudbees-core-oc.repo https://downloads.cloudbees.com/cloudbees-core/traditional/operations-center/rolling/rpm/cloudbees-core-oc.repo▼
```
This repository is used to automate the installation and upgrade of the operations center 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/operations-center/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 operations center, update your operating system 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 operations center application; the Yum command is:
```
sudo yum install cloudbees-core-oc▼
```
The DNF command is:
```
sudo dnf install cloudbees-core-oc▼
```
Once the installation process is completed, the operations center automatically starts running and by default, is accessible on port 8888.

To access the operations center, open your favorite browser and access the URL: http://operations-center-url:8888/.

For details about stopping and re-starting the operations center, refer to Stopping and (re-)starting the service on Linux.

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

Installing on OpenSUSE

On OpenSUSE, the operations center can be installed using the Zypper package manager.

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

To access the operations center, open your favorite browser and access the URL: http://operations-center-url:8888/.

Stopping and (re-)starting the service on Linux

To stop the operations center, execute this command:

sudo service cloudbees-core-oc stop▼

To re-start the operations center, execute this command:

sudo service cloudbees-core-oc start▼

Installing on Microsoft Windows

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

The operations center 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 operations center installer. Read more about installing .NET Frameworks on Windows 7 on the Microsoft Docs and TechHit sites.

To install operations center 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 operations center from this web site’s 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 operations center, which, by default, is accessible through port 8888.

To access operations center, open your favorite browser and access the URL: http://operations-center-url:8888/.

Running the WAR file directly

Operations center can be run directly on a JVM, which in turn is running on any of the supported operating systems, using the operations center WAR file.

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

To run operations center 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 operations center (named core-oc.war) from this web site’s downloads page and move it to an appropriate directory on your operating system’s file system.

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

To access operations center, open your favorite browser and access the URL: http://operations-center-url:8888/.

Note:

You can change the port by specifying the --httpPort option when running the
java -jar cloudbees-core-oc.war command. For example, to make operations center accessible through port 9090, start operations center using the command:
java -jar cloudbees-core-oc.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 operations center 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 operations center) can be run on any operating system or cloud service that is also running Docker. However, CloudBees only supports running operations center 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.

The operations center 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 operations center in Docker

Complete the following steps to download and run the operations center 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 operations center in Docker.)

Download the Docker image for operations center 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-oc (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-oc` image below) when it is shut down. This keeps your Docker environment tidy if you need to quit operations center.
2	( Optional ) Runs the `cloudbees/cloudbees-core-oc` 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-oc` 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 operations center on your host machine through port 49000.
4	( Optional ) Maps port 50000 of the `cloudbees/cloudbees-core-oc` 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-oc` (operations center) container. JNLP-based agents communicate with operations center through TCP port 50000 by default. You can change this port number on your operations center instance through the Manage Jenkins > Configure Global Security page. If you were to change operations center’s TCP port for JNLP agents value to 51000 (for example), then you would need to re-run operations center (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 operations center and the first value is the port number on the operations center’s host machine through which the JNLP-based agents communicate (to operations center) - i.e. 52000.
5	( 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 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`.
6	The `cloudbees/cloudbees-core-oc` 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-oc`. This Docker image is also accessible from the `cloudbees/cloudbees-core-oc` 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-oc▼

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.

The operations center can be run on Apache Tomcat version 8.5, using the operations center WAR file.

Ensure that you have met the appropriate hardware and software 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 operations center (named core-oc.war) from this web site’s downloads page.

Other versions of the operations center Java WAR file can be obtained from the operations center WAR file downloads page.
Deploy the operations center 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 operations center into Tomcat is to:
1. Copy the operations center WAR file (core-oc.war) to the $CATALINA_BASE/webapps or $CATALINA_HOME/webapps` directory.
2. Start Tomcat.
3. Access operations center through the URL:
  http://tomcat-url:port-number/cloudbees-core-oc.
To run Tomcat to host operations center only:
1. Remove everything from the $CATALINA_BASE/webapps or $CATALINA_HOME/webapps directory.
2. Copy the operations center WAR file (core-oc.war) to this directory.
3. Start Tomcat.
4. Access operations center through the URL:
  http://tomcat-url:port-number.
Ensure the system property org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH has been set to true, which allows encoded slashes (i.e. '%2F' and '%5C' for forward and back slashes) as path delimiters. If you do not set this property, operations center 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).
Operations center and client controllers cannot be hosted on the same JVM.