Migrating from Jenkins LTS

This topic covers migration from Jenkins LTS to CloudBees Jenkins Distribution.

Similar to Jenkins, CloudBees Jenkins Distribution can run as a stand-alone Java process inside a Java servlet container engine (like Jetty). Regardless of the configuration, please ensure the machine running CloudBees Jenkins Distribution meets the system requirements before continuing.

These instructions assume that your Jenkins instance version is a recent LTS. CloudBees Jenkins Distribution is based upon the Jenkins LTS: for example, CloudBees Jenkins Distribution <version> is itself based on Jenkins <version> (and is therefore a straight-forward upgrade).

If your Jenkins version is one of the "weekly" releases, or a Jenkins LTS version older than 2.150.2, please contact CloudBees Support for an Assisted Update.

An important note about users

Important
The user that runs Jenkins is CHANGING to cloudbees-jenkins-distribution.

It is very important that:

  1. The cloudbees-jenkins-distribution user exists on your system.

  2. The cloudbees-jenkins-distribution user has the appropriate privileges to run Jenkins.

  3. The cloudbees-jenkins-distribution user is running in a secure manner to prevent privilege-escalation exploits.

If you have questions about setting up the cloudbees-jenkins-distribution user, please contact CloudBees Support

Linux

When upgrading from Jenkins on Linux, this guide assumes that the current Jenkins instance is using the Jenkins project’s official Linux (rpm, deb) packages, and that the upgrading CloudBees Jenkins Distribution instance will also use Linux packages.

These instructions also assume that the home directory, commonly referred to as JENKINS_HOME in configuration scripts and documentation, is /var/lib/jenkins.

Red Hat Enterprise Linux / CentOS

To migrate from Jenkins to CloudBees Jenkins Distribution on Red Hat Enterprise Linux or CentOS systems, follow these instructions.

Remove the previously installed jenkins package

Replace the previously installed jenkins package with the cloudbees-jenkins-distribution package:

yum remove jenkins (1)
ln -s /var/lib/jenkins /var/lib/cloudbees-jenkins-distribution (2)
  1. This command removes the previously installed jenkins package from the system.

  2. This command creates a symbolic link to the old JENKINS_HOME so that CloudBees Jenkins Distribution can re-use the same home directory and its contents.

Install CloudBees Jenkins Distribution for Red Hat Enterprise Linux / CentOS

Administrators running Red Hat-based distributions, such as Red Hat Enterprise Linux, Fedora, Oracle Linux, and CentOS, first need to set up the RPM repository for CloudBees Jenkins Distribution and import the key.

  1. Set up the RPM repository:

    sudo wget -O /etc/yum.repos.d/cloudbees-jenkins-distribution.repo https://downloads.cloudbees.com/cloudbees-jenkins-distribution/rolling/rpm/cloudbees-jenkins-distribution.repo
  2. Import the CloudBees key:

    sudo rpm --import https://downloads.cloudbees.com/cloudbees-jenkins-distribution/rolling/rpm/cloudbees.com.key
    Note

    If the CloudBees key has already been imported on the machine, the rpm --import command will fail. This error can be safely ignored.

  3. Once the repository and key have been set up, CloudBees Jenkins Distribution can be installed with yum via:

    sudo yum install cloudbees-jenkins-distribution
  4. Set the cloudbees-jenkins-distribution service to automatically start on boot:

    sudo chkconfig --add cloudbees-jenkins-distribution
    sudo /etc/init.d/cloudbees-jenkins-distribution start

Change ownership

Once installation is complete, change the ownership of the previous JENKINS_HOME to the cloudbees-jenkins-distribution user:

chown -R cloudbees-jenkins-distribution:cloudbees-jenkins-distribution /var/lib/jenkins

Confirm settings

Any changes you made to /etc/sysconfig/jenkins are saved to /etc/sysconfig/jenkins.rpmsave when the jenkins package is removed. If necessary, manually review this file, and copy the appropriate settings into /etc/sysconfig/cloudbees-jenkins-distribution.

Start CloudBees Jenkins Distribution

After completing these steps, you can start CloudBees Jenkins Distribution with the command service cloudbees-jenkins-distribution start and move on to the post-migration tasks.

Debian / Ubuntu

To migrate from Jenkins to CloudBees Jenkins Distribution on Debian or Ubuntu systems, follow these instructions.

Remove the previously installed jenkins package

Replace the previously installed jenkins package with the cloudbees-jenkins-distribution package:

apt-get remove jenkins (1)
ln -s /var/lib/jenkins /var/lib/cloudbees-jenkins-distribution (2)
  1. This command removes the previously installed jenkins package from the system.

  2. This command creates a symbolic link to the old JENKINS_HOME so that CloudBees Jenkins Distribution can re-use the same home directory and its contents.

Install CloudBees Jenkins Distribution for Debian / Ubuntu

Administrators running Debian-based distributions such as Debian or Ubuntu will need to add an APT repository and key in order to install CloudBees Jenkins Distribution.

  1. To use the Debian package repository of CloudBees Jenkins Distribution to automate installation and upgrade, first add the key to your system:

    wget -q -O - https://downloads.cloudbees.com/cloudbees-jenkins-distribution/rolling/debian/cloudbees.com.key | sudo apt-key add -
  2. Edit /etc/apt/sources.list and add the entry for CloudBees Jenkins Distribution:

    deb https://downloads.cloudbees.com/cloudbees-jenkins-distribution/rolling/debian binary/
  3. Update your local package index:

    sudo apt-get update
  4. Install CloudBees Jenkins Distribution:

    sudo apt-get install cloudbees-jenkins-distribution
    Caution

    Older versions of Debian and Ubuntu do not provide a Java 8 package and CloudBees Jenkins Distribution may fail to install as a result. Using newer versions of these distributions which provide Java 8 is strongly recommended.

  5. Start the cloudbees-jenkins-distribution service:

    service cloudbees-jenkins-distribution start

Change ownership

Once installation is complete, change the ownership of the previous JENKINS_HOME to the cloudbees-jenkins-distribution user:

chown -R cloudbees-jenkins-distribution:cloudbees-jenkins-distribution /var/lib/jenkins

Confirm settings

If you made changes to /etc/default/jenkins, review this file, and copy the appropriate settings into /etc/default/cloudbees-jenkins-distribution.

Start CloudBees Jenkins Distribution

After completing these steps, you can start CloudBees Jenkins Distribution with the command service cloudbees-jenkins-distribution start and move on to the post-migration tasks.

openSUSE / SUSE Linux

To migrate from Jenkins to CloudBees Jenkins Distribution on openSUSE- or SUSE Linux-based systems, follow these instructions:

Remove the previously installed jenkins package

Replace the previously installed jenkins package with the cloudbees-jenkins-distribution package:

zypper remove jenkins (1)
ln -s /var/lib/jenkins /var/lib/cloudbees-jenkins-distribution (2)
  1. This command removes the previously installed jenkins package from the system.

  2. This command creates a symbolic link to the old JENKINS_HOME so that CloudBees Jenkins Distribution can re-use the same home directory and its contents.

Install CloudBees Jenkins Distribution for openSUSE / SUSE Linux

Use the zypper command to install CloudBees Jenkins Distribution on openSUSE-based distributions.

  1. First, add the CloudBees RPM repository:

    sudo zypper addrepo -f https://downloads.cloudbees.com/cloudbees-jenkins-distribution/rolling/opensuse/ cloudbees-jenkins-distribution
  2. Next, run:

    sudo zypper install cloudbees-jenkins-distribution

Change ownership

Once installation is complete, change the ownership of the previous JENKINS_HOME to the cloudbees-jenkins-distribution user:

chown -R cloudbees-jenkins-distribution:cloudbees-jenkins-distribution /var/lib/jenkins

Confirm settings

Any changes you made to /etc/sysconfig/jenkins are saved to /etc/sysconfig/jenkins.rpmsave when the jenkins package is removed. If necessary, manually review this file, and copy the appropriate settings into /etc/sysconfig/cloudbees-jenkins-distribution.

Start CloudBees Jenkins Distribution

After completing these steps, you can start CloudBees Jenkins Distribution with the command service cloudbees-jenkins-distribution start and move on to the post-migration tasks.

Microsoft Windows

To migrate from Jenkins to CloudBees Jenkins Distribution on Microsoft Windows systems, follow these instructions.

Remove the previously installed jenkins package and rename folders

Remove the previously installed jenkins package:

  1. Stop the jenkins service and delete it.

  2. Rename the folder where the jenkins service was running from Program Files (x86)/Jenkins to Program Files (x86)/CloudBeesJenkinsDistribution

    Note
    Folder names may vary depending on where the Jenkins LTS was installed.

Download, install, and run CloudBees Jenkins Distribution for Windows

To run CloudBees Jenkins Distribution on Microsoft Windows, use the MSI file from the CloudBees Jenkins Distribution download site.

  1. Download the cloudbees-jenkins-distribution.zip file, and the SHA256 checksum file.

  2. The checksum file can be used to verify that the cloudbees-jenkins-distribution.zip is correct. Compare the contents of cloudbees-jenkins-distribution.zip.sha256 with the output of the following PowerShell command:

    $(CertUtil -hashfile D:\Users\USER\Downloads\cloudbees-jenkins-distribution.zip SHA256)[1] -replace " ",""
  3. Unpack the archive and execute the CloudBees Jenkins Distribution installer, cloudbees-jenkins-distribution.msi.

    Note

    The CloudBees Jenkins Distribution installer for Microsoft Windows requires a 64-bit operating system and a compatible .NET framework (2.0, 3.5.1, 4.0) in order to be installed as a service. Most Microsoft Windows versions install a compatible framework by default.

After the process has completed, CloudBees Jenkins Distribution will start automatically and be available on port 8080 by default.

Docker

To migrate from Jenkins to CloudBees Jenkins Distribution on Docker-based systems, follow these instructions:

Stop and delete the previously installed container service

Stop and delete the previously installed container service and update it with an appropriate Docker image.

docker stop <Jenkins container name> && docker rm <Jenkins container name> (1)
docker pull cloudbees/cloudbees-jenkins-distribution (2)
docker run --name <Jenkins container name> -p 18080:8080 -v /tmp/docker/:/var/jenkins_home [IMAGE_ID] (3)
  1. This command stops and deletes the previous container.

  2. This command pulls a new Docker image from CloudBees.

  3. This command launches a container from the new image with the same name (<Jenkins container name>) and same JENKINS_HOME volume.

After the process has completed, CloudBees Jenkins Distribution will start automatically and be available on port 8080 by default, and you can move on to the post-migration tasks.

Stand-alone WAR file

While it is strongly recommended that administrators rely on the native packages above, CloudBees Jenkins Distribution can be run as a stand-alone WAR file with an existing JENKINS_HOME.

Install and run CloudBees Jenkins Distribution for stand-alone WAR files

  1. Download the WAR file for CloudBees Jenkins Distribution; for your operating system and copy it to where you wish to run CloudBees Jenkins Distribution.

  2. Copy the file to the directory where you wish to run CloudBees Jenkins Distribution.

  3. Open a terminal and run the command:

    java -jar cloudbees-jenkins-distribution.war
  4. The process output generates a password offset by three rows of asterisks above and below the text. Copy the password. The password is also saved in a directory like /users/<username>.jenkins/secrets/initialAdminPassword, where username is replaced with your username. The exact path may vary depending upon your operating system.

    *************************************************************
    *************************************************************
    *************************************************************
    
    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
    
    *************************************************************
    *************************************************************
    *************************************************************
  5. The terminal portion is complete when the output reads:

    INFO: Obtained the updated data file for hudson.tools.JDKInstaller
    Jan 24, 2019 4:38:57 PM com.cloudbees.jenkins.plugins.assurance.model.UpdateSiteDataProvider$Value get
    INFO: Beekeeper is parsing UpdateSite cloudbees-jenkins-distribution-offline
    Jan 24, 2019 4:38:57 PM com.cloudbees.jenkins.plugins.assurance.model.UpdateSiteDataProvider$Value get
    INFO: Beekeeper is parsing UpdateSite cap-cloudbees-jenkins-distribution
    Jan 24, 2019 4:42:42 PM hudson.model.AsyncPeriodicWork$1 run
    INFO: Started telemetry collection
    Jan 24, 2019 4:42:42 PM hudson.model.AsyncPeriodicWork$1 run
    INFO: Finished telemetry collection. 1 ms

To complete the migration, set the JENKINS_HOME environment variable to the existing Jenkins home directory. For example:

shell% JENKINS_HOME=/var/lib/jenkins java -jar cloudbees-jenkins-distribution.war

Post-migration tasks

Completing post-install configuration

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 at support@cloudbees.com 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). Email sales@cloudbees.com to obtain a register your product. Once you have the free license from CloudBees, select license key and paste the License Key and License Certificate from your registration in to their 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.

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