Table of contents

CloudBees Core on traditional platforms installation guide


Installing Client Masters

The installation instructions in this chapter describes how to install a Client Master on your chosen hardware or virtual machine and the requirements for a Client Master installation.

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

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

Notes: CloudBees support for Client Master installations:

  • CloudBees provides support for the following Client Master installation scenarios:

    • Client Masters 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 Masters 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 Master installation scenarios:

    • Attempting to install or run Client Masters on mobile devices or mobile device operating systems.

    • Installing or running Client Masters 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 Core on traditional platforms in: Support Lifecycle and Update Policies for CloudBees Core on traditional platforms.

About Client Master releases

CloudBees Core 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 Core on Traditional Platforms build number. This z digit allows an existing CloudBees Core on Traditional Platforms package to perform an "in-place" installation of files (during upgrades) without the need to uninstall CloudBees Core on Traditional Platforms packages first.

See the CloudBees Core on Modern Cloud Platforms Release Notes page to access the release notes for CloudBees Core on Traditional Platforms and the Client Master.

Installing on Linux

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

To run a Client Master 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 Master can be installed using the Apt package management tools.

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

  2. Ensure that you have met all the JVM requirements.

  3. Add the Apt key of the Debian package repository for the Client Master application to your operating system with this command:

    sudo apt-key adv --keyserver keyserver.ubuntu.com --recv 38E2F5F39FF90BDA

    This repository is used to automate the installation and upgrade of the Client Master application on your operating system.

    Note

    You can also add this Apt key with the following command:

    wget -q -O - https://downloads.cloudbees.com/cloudbees-core/traditional/client-master/rolling/debian/cloudbees.com.key | sudo apt-key add -
  4. Add the following entry to Apt’s "sources" list file (/etc/apt/sources.list):

    deb https://downloads.cloudbees.com/cloudbees-core/traditional/client-master/rolling/debian binary/
  5. Update your local Apt package list with this command:

    sudo apt-get update
  6. Install the Client Master application:

    sudo apt-get install cloudbees-core-cm

    Once the installation process is completed, the Client Master automatically starts running and by default, is accessible on port 8080.

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

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

Note

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

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

  2. Ensure that you have met all the JVM requirements.

  3. Add the package manager repository for the Client Master 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 Master application on your operating system.

  4. Add the key of this repository to your operating system:

    sudo rpm --import "https://keyserver.ubuntu.com/pks/lookup?op=get&fingerprint=on&search=0x38E2F5F39FF90BDA"
    Note

    You can also add this key with the following command:

    sudo rpm --import https://downloads.cloudbees.com/cloudbees-core/traditional/client-master/rolling/rpm/cloudbees.com.key

    These commands may fail if you previously imported the key (and already have it added to your operating system). In such cases, ignore the error and continue on.

  5. Before installing the Client Master, 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
  6. Install the Client Master 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 Master automatically starts running and by default, is accessible on port 8080.

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

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

Note

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 Master can be installed using the Zypper package manager.

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

  2. Ensure that you have met all the JVM requirements.

  3. Add the package manager repository for the Client Master 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 Master application on your operating system.

  4. Install the Client Master application:

    sudo zypper install cloudbees-core-cm

    Once the installation process is completed, the Client Master automatically starts running and by default, is accessible on port 8080.

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

Stopping and (re-)starting the service on Linux

To stop a Client Master instance, execute this command:

sudo service cloudbees-core-cm stop

To (re-)start the Client Master 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 Master on Microsoft Windows, which is configured as a Windows service that runs upon Windows startup.

Note

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

To install the Client Master on Windows:

  1. Ensure that you have met the appropriate hardware requirements and that your operating system has met the JVM requirements above.

  2. Download the Windows installer file (i.e. a Zip archived MSI file) [2] for the Client Master from this web site’s downloads page.

    Note

    Other versions of the Client Master Windows installer file can be obtained from the Client Master Windows installer downloads page.

  3. 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 Master, which by default is accessible through port 8080.

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

Running the WAR file directly

A Client Master can be run directly on a JVM, which in turn is running on any of the operating systems listed above, using the Client Master WAR file. [1]

Note

The Client Master 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 Master WAR on operating systems other than those listed above.

To run the Client Master directly on your operating system JVM:

  1. Ensure that you have met the appropriate hardware requirements and that your operating system has met the JVM requirements above.

  2. Download the Java WAR file for the Client Master (named cloudbees-core-cm.war) from this web site’s downloads page and move it to an appropriate directory on your operating system’s file system.

    Note

    Other versions of the Client Master Java WAR file can be obtained from the Client Master WAR file downloads page.

  3. In a terminal/command prompt (window), cd to the directory containing the Client Master WAR file
    (cloudbees-core-cm.war).

  4. Start the Client Master with this command:

    java -jar cloudbees-core-cm.war

    By default, the Client Master is accessible through port 8080.

To access the Client Master, 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 Master accessible through port 9090, start the Client Master 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 Master 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 Master) can be run on any operating system or cloud service that is also running Docker. However, CloudBees only supports running a Client Master 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 Master 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.

Caution

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 Master in Docker

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

  2. Download the Docker image for the Client Master and run it as a container in Docker using the following
    docker run command:

    docker run \
      -u root \
      --rm \ (1)
      -d \ (2)
      -p 8080:8080 \ (3)
      -p 50000:50000 \ (4)
      -v jenkins-data:/var/jenkins_home \ (5)
      -v /var/run/docker.sock:/var/run/docker.sock \ (6)
      cloudbees/cloudbees-core-cm (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-core-cm image below) when it is shut down. This keeps your Docker environment tidy if you need to quit the Client Master.

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

    6. ( Optional ) /var/run/docker.sock represents the Unix-based socket on which the Docker daemon listens. This mapping allows the cloudbees/cloudbees-core-cm container to communicate with the Docker daemon, which is required if the cloudbees/cloudbees-core-cm 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-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.
      Notes: 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).

    Note: 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/jenkins_home \
      -v /var/run/docker.sock:/var/run/docker.sock \
      cloudbees/cloudbees-core-cm

Running in Apache Tomcat

A Client Master can be run on Apache Tomcat version 8.5, using the Client Master WAR file. [1]

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

  2. Download the Java WAR file for the Client Master (named cloudbees-core-cm.war) from this web site’s downloads page.

    Note

    Other versions of the Client Master Java WAR file can be obtained from the Client Master WAR file downloads page.

  3. Deploy the Client Master 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 Master into Tomcat is to:

    1. Copy the Client Master WAR file (cloudbees-core-cm.war) to the $CATALINA_BASE/webapps or $CATALINA_HOME/webapps directory.

    2. Start Tomcat.

    3. Access the Client Master through the URL:
      http://tomcat-url:port-number/cloudbees-core-cm.

  • To run Tomcat to host the Client Master only:

    1. Remove everything from the $CATALINA_BASE/webapps or $CATALINA_HOME/webapps directory.

    2. Copy the Client Master WAR file (cloudbees-core-cm.war) to this directory.

    3. Start Tomcat.

    4. Access the Client Master 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, the Client Master 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 Master and Operations Center server cannot be hosted on the same JVM.