Migrate CloudBees CI on traditional platforms from Tomcat to a CloudBees Linux package

6 minute read

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.

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

This guide explains how to migrate your client controller and operations center instance from Tomcat to one of the CloudBees Linux packages.

Benefits of migrating include:

  • Tomcat includes its own class library which is loaded in addition to the Java Development Kit (JDK) and CloudBees CI classes. Depending on how Tomcat is configured, the order of class loading can break CloudBees CI plugins in subtle and hard to diagnose ways.

  • CloudBees CI already includes Winstone and Jetty inside the .war file, so an additional web application server is not required.

  • The Jenkins community Servlet Container Support Policy now provides limited or no support for containers other than the bundled Winstone and Jetty.

  • Reduced maintenance burden by moving to a Linux package that includes service management (via systemd), and a built-in web server (via Winstone and Jetty).

These steps provide general guidance that should be applicable to all customers, but in unique situations or if unsure, please reach out to CloudBees Support for additional guidance.

Prepare for the migration

Before starting the migration, CloudBees recommends that you complete the following steps to prepare for the migration.

  1. As all migrations carry a risk of data loss, CloudBees strongly recommends backing up your $JENKINS_HOME prior to migrating. For more information, refer to Backup and restore.

  2. Determine if you are going to migrate to new hardware or a new OS version at the same time as migrating the CloudBees software.

    If you choose to migrate to new hardware or a new OS at the same time, it makes troubleshooting the root cause of an issue more difficult, and requires more involvement from your Linux system administrators and network administrators during the migration if there are problems (for example, if a network firewall needs to be reconfigured).

    However, there are certain scenarios where an OS upgrade is required. For example, if you are running an OS that does not have systemd, you must migrate to a newer OS version before performing the upgrade and migration of CloudBees software. For more information, refer to Advanced topic: Migrate to new machines at the same time as migrating from Tomcat.

Migrate the service options

It is very likely that you have already fine-tuned the Tomcat Java options to improve performance of CloudBees CI. You could have added them via Tomcat setenv script, directly in a catalina script, or a distribution-specific configuration file. These options should be migrated to the CloudBees Linux package-specific configuration file. Refer to How to add Java arguments to Jenkins? to determine which file you need to update.

Note that Tomcat-specific options are an exception. For example, org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true is required on Tomcat, but it does not apply to CloudBees Linux packages, so it can be omitted.

If the .war file was not deployed as ROOT.war, add its name as a --prefix argument to the Jenkins arguments. For example, if the operations center was deployed as cjoc.war, add --prefix=/cjoc. For more information, refer to How to add Jenkins command line options to CloudBees CI (CloudBees Core)?.

Migrate the operations center from Tomcat to a CloudBees Linux package

  1. For the desired CloudBees CI version, install the operations center for CloudBees CI on traditional platforms.

    For example, to install a specific version on Fedora/CentOS/RHEL, run:

    sudo yum install cloudbees-core-oc-2.346.4.1
    ▼

    To install a specific version on Debian/Ubuntu, run:

    sudo apt-get install cloudbees-core-oc=2.346.4.1
    ▼

  2. Stop the new service:

    sudo systemctl stop cloudbees-core-oc
    ▼

  3. Migrate the service options.

  4. Stop the Tomcat service.

  5. Create a copy of the $JENKINS_HOME directory. (for example, named jenkins-oc) for CloudBees CI (named cloudbees-core-oc) and change the ownership of this new directory to the new cloudbees-core-oc user:

    cd /var/lib/
sudo cp -rf jenkins-oc/* cloudbees-core-oc/
cd cloudbees-core-oc/
sudo chown -R cloudbees-core-oc:cloudbees-core-oc .
    ▼

  6. Start your new CloudBees CI operations center instance:

    sudo systemctl start cloudbees-core-oc
    ▼

  7. (Optional) If the migration of your operations center instance to CloudBees CI ran successfully, you can remove the old $JENKINS_HOME and Tomcat webapp. For example:

    rm -rf /var/lib/jenkins-oc
rm /var/lib/tomcat/webapps/cjoc.war
    ▼

Migrate a controller from Tomcat to a CloudBees Linux package

  1. For the desired CloudBees CI version, install the client controller for CloudBees CI on traditional platforms.

    For example, to install a specific version on Fedora/CentOS/RHEL, run:

    sudo yum install cloudbees-core-cm-2.346.4.1
    ▼

    To install a specific version on Debian/Ubuntu, run:

    sudo apt-get install cloudbees-core-cm=2.346.4.1
    ▼

  2. Stop the new service:

    sudo systemctl stop cloudbees-core-cm
    ▼

  3. Migrate the service options.

  4. Stop the Tomcat service.

  5. Create a copy of the $JENKINS_HOME directory. (for example, named jenkins) for CloudBees CI (named cloudbees-core-cm) and change the ownership of this new directory to the new cloudbees-core-cm user:

    cd /var/lib/
sudo cp -rf jenkins/* cloudbees-core-cm/
cd cloudbees-core-cm/
sudo chown -R cloudbees-core-cm:cloudbees-core-cm .
    ▼

  6. Start your new CloudBees CI client controller instance:

    sudo systemctl start cloudbees-core-cm
    ▼

  7. (Optional) If the migration of your client controller instance to CloudBees CI ran successfully, you can remove the old $JENKINS_HOME and Tomcat webapp. For example:

    rm -rf /var/lib/jenkins
rm /var/lib/tomcat/webapps/jenkins.war
    ▼

Advanced topic: Migrate to new machines at the same time as migrating from Tomcat

If you prefer to use a new machine, install CloudBees CI on it, and then migrate your $JENKINS_HOME data to this new machine, you must complete the following steps:

  1. Migrate to a new machine for the operations center at the same time as migrating from Tomcat.

  2. Migrate to a new machine for client controller at the same time as migrating from Tomcat.

Migrate to a new machine for the operations center at the same time as migrating from Tomcat

  1. Provision a new machine for your operations center running a supported OS version. For more information, refer to Supported platforms for CloudBees CI on traditional platforms.

  2. For the desired CloudBees CI version, install the operations center for CloudBees CI on traditional platforms.

    For example, to install a specific version on Fedora/CentOS/RHEL, run:

    sudo yum install cloudbees-core-oc-2.346.4.1
    ▼

    To install a specific version on Debian/Ubuntu, run:

    sudo apt-get install cloudbees-core-oc=2.346.4.1
    ▼

  3. Stop the new service:

    sudo systemctl stop cloudbees-core-oc
    ▼

  4. Take the backup of your $JENKINS_HOME data taken from your existing machine (for example, /var/lib/jenkins-oc. For more information, refer to Backup and restore.

  5. Restore the backup onto the new machine running CloudBees CI at /var/lib/cloudbees-core-oc. For more information, refer to Restore backup files manually.

    1. After restoring, change the permissions of $JENKINS_HOME to use the new JENKINS_USER setting by running:

      sudo chown -R cloudbees-core-oc:cloudbees-core-oc /var/lib/cloudbees-core-oc
      ▼

    2. If you are changing the URL for your operations center, reset the identity of the operations center:

      cd /var/lib/cloudbees-core-oc
rm secret.key* license.xml identity.key.enc
      ▼

      1. Check /var/lib/cloudbees-core-oc/config.xml and /var/lib/cloudbees-core-oc/jenkins.model.JenkinsLocationConfiguration.xml for URL-specific options. Replace the Origin URL with the Target URL.

    3. If High Availability (active/passive) was previously enabled, remove the jgroups directory:

      cd /var/lib/cloudbees-core-oc
rm -r jgroups/
      ▼

  6. Migrate the service options.

  7. Start the service:

    sudo service cloudbees-core-oc start
    ▼

Migrate to a new machine for client controller at the same time as migrating from Tomcat

  1. Provision a new machine for your client controller running a supported OS version. For more information, refer to Supported platforms for CloudBees CI on traditional platforms.

  2. For the desired CloudBees CI version on the new client controller machine, install the client controller for CloudBees CI on traditional platforms.

    For example, to install a specific version on Fedora/CentOS/RHEL, run:

    sudo yum install cloudbees-core-cm-2.346.4.1
    ▼

    To install a specific version on Debian/Ubuntu, run:

    sudo apt-get install cloudbees-core-cm=2.346.4.1
    ▼

  3. Stop the service:

    sudo service cloudbees-core-cm stop
    ▼

  4. Take the backup of your $JENKINS_HOME data taken from your existing machines (for example, /var/lib/jenkins. For more information, refer to Backup and restore.

  5. Restore the backup on to the new machines at /var/lib/cloudbees-core-cm. For more information, refer to Restore backup files manually.

    1. After restoring, change the permissions of $JENKINS_HOME to use the new JENKINS_USER setting by running:

      sudo chown -R cloudbees-core-cm:cloudbees-core-cm /var/lib/cloudbees-core-cm
      ▼

    2. (Optional) If the client controller was connected and the operations center URL changed, remove the connection details that point to the old operations center URL:

      cd /var/lib/cloudbees-core-cm
rm license.xml operations-center-cloud* operations-center-client* com.cloudbees.opscenter.client.plugin.OperationsCenterRootAction.xml
      ▼

    3. (Optional) If you are changing the URL for your client controller, reset the identity of the client controller:

      cd /var/lib/cloudbees-core-cm
rm secret.key* license.xml identity.key.enc
      ▼

      1. Check /var/lib/cloudbees-core-cm/config.xml and /var/lib/cloudbees-core-cm/jenkins.model.JenkinsLocationConfiguration.xml for URL-specific options. Replace the Origin URL with the Target URL.

    4. If High Availability (active/passive) was previously enabled, remove the jgroups directory:

      cd /var/lib/cloudbees-core-cm
rm -r jgroups/
      ▼

  6. Migrate the service options.

    Ensure any startup arguments that mention the old machine’s hostname are modified to the new machine’s hostname.

  7. (Optional) Remove the build agents from the new controller. This should be done if you plan to keep the old controller instance running at the same time as CloudBees CI. If you have Tomcat disabled and do not plan to start it again, this step can be skipped.

    This step is important so that the same build agents using the same remote work directories are not connected to two different client controllers, which would cause file collisions and corruption on the agent workspaces. 
    cd /var/lib/cloudbees-core-cm
rm -r nodes/*
    ▼

  8. Start the service:

    sudo service cloudbees-core-cm start
    ▼

  9. If you are unable to sign in to the client controller due to no connection to the operations center, disable security.

  10. (Optional) If the URLs of the operations center or controller (or both) changed, you must connect your new client controller to your new operations center.

    1. Navigate to the operations center dashboard.

    2. Locate the client controller.

    3. Disconnect the client controller and release it if it is already connected.

    4. Use the Push connection details section to add the new client controller URL and select Push configuration to connect the client controller.

If you have any troubles with these steps, please contact CloudBees Support.

Migrate managed controllers and team controllers