Installing CloudBees Analytics to an existing CloudBees CI on traditional platforms environment

8 minute read

Installations of CloudBees CI on traditional platforms can take advantage of the analytics capabilities of CloudBees Software Delivery Automation.

Follow these steps in the order listed to complete the installation:

Pre-installation requirements

Before starting the installation process, do the following:

  • Contact CloudBees Support to obtain the executable files for the CloudBees CD/RO and CloudBees Analytics installers.

  • Review the CloudBees CI on traditional platforms + CloudBees Analytics architecture details to become familiar with CloudBees CI and CloudBees Software Delivery Automation concepts and terminology.

Upgrading CloudBees CI on traditional platforms

Before upgrading

Take a SNAPSHOT of your CloudBees CI platform. For the Operations Center and every controller:

  • Generate a support bundle. It will help in case there are problems with the upgrade or to know what plugins were upgraded in the process.

  • Backup your instance before starting the upgrade. The minimal backup is a copy of your ${JENKINS_HOME} directory. If the BUILD_DIRECTORY is out of the ${JENKINS_HOME}, you must back it up as well.

Note: In the case something unexpected happens, the rollback process in based on the Backup of your instance.

For client controllers connected to Operations Center:
  • Operations Center must be upgraded first, then client controllers.

  • The client controller connected to the Operations Center does not have to be at the same version.

The version of Operations Center must always be more recent or as old as the version of the client controllers that are connected to the Operations Center (Operations Center >= client controller version).

Recommendations

Setup a test environment

This is ideally a full test environment with the Operations Center and client controllers and requires a test license. If this is not feasible, just having a test controller with representative jobs will work.

Enable CloudBees Assurance Program

Ensure that CloudBees Assurance Program is enabled to avoid plugin dependency issues or incorrect versions installed.

Upgrade to latest version

CloudBees recommends that you always upgrade to the latest version of your CloudBees product, ensuring a wider lifecycle support coverage plus more security patches added (CloudBees Security Advisory), more fixed issues, and more new features included.

Upgrade plugins

CloudBees recommends that you upgrade your plugins before upgrading a Jenkins instance. For instructions on upgrading plugins, see Upgrading plugins from the Plugin Manager. Run tests after upgrading the plugins to ensure that the upgrades are functioning as expected.

Upgrade instance where it is running

CloudBees highly recommends that you upgrade Jenkins to the same location where it is running even if it is in the production environment. Doing a backup of $JENKINS_HOME and the $BUILD_DIR - in case it is outside the default location - should be enough to revert to the previous status.

CloudBees does not recommend that you keep two different instances working at the same time. This is to avoid downtime while performing the upgrade unless you really know what you are doing - it will be very difficult to replicate the exactly same environment.

  • JNLP agent will not work correctly as the $JENKINS_URL location will be different.

  • Credentials might fail in case the secret is not the same on both instances.

  • The OS might not be configured in the same way. i.e ulimit.

  • The CloudBees CI configuration might not be correctly replicated.

Stop using Apache Maven builds (if possible)

The Maven plugin plugin is not recommended as it is considered unreliable by the Community. Therefore, it is recommended that you migrate jobs using this plugin to Pipeline Jobs with the Maven integration.

If (and only if) you are able to migrate your Maven plugin builds, please carefully read the Maven jobs and Java versions compatibility guide.

Upgrade process

Visit CloudBees downloads

Go to the downloads page. Select your desired distribution type, and review the instructions.

  • WAR

  • RPM

  • OpenSuse

  • Debian

  • Microsoft Windows

  • Docker

Installation procedures

WAR

If your CloudBees CI instance is run with the command java -jar cloudbees-core-cm.war or java -jar cloudbees-core-oc.war, you can simply replace the jenkins.war file with the latest version.

Linux
Red Hat / CentOS
  • Controller - yum upgrade cloudbees-core-cm

  • Operations Center - yum upgrade cloudbees-core-oc

RPM/YUM with High Availability

The RPM package contains a post-install script to ensure ownership on several files including JENKINS_HOME. Therefore if High Availability is setup, this could lead to I/O Errors - for example when upgrading one node while another one is still running. More information is available in JENKINS-23273.

To workaround this problem, you can skip this script by adding the property JENKINS_INSTALL_SKIP_CHOWN="true" under /etc/sysconfig/jenkins.

Debian / Ubuntu
  • Controller - apt-get update && apt-get install cloudbees-core-cm

  • Operations Center - apt-get update && apt-get install cloudbees-core-oc

openSUSE / SUSE Linux
  • Controller - zypper install cloudbees-core-cm

  • Operations Center - zypper install cloudbees-core-oc

Servlet container

Once a .war archive has been downloaded, follow the servlet container’s existing application deployment process.

When using servlet containers, CloudBees CI will set the JENKINS_HOME to the $APP_SERVER_USER/.jenkins/ folder. If the servlet container installation does not include write permissions to this folder for this user (sometimes done for security), you either need to grant appropriate permissions or override this setting by adding the "-DJENKINS_HOME=$MY_JENKINSPATH" argument in your servlet container startup. Refer to the servlet container’s documentation for how to add startup arguments.

Tomcat

Use environment variable CATALINA_OPTS to add:

  • -Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true.

  • -Dorg.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH=true which is needed for Blue Ocean.

CloudBees recommends that you configure it in the script $CATALINA_BASE/bin/setenv.sh (Linux) or %CATALINA_BASE%\bin\setenv.bat (Microsoft Windows) that you’ll create to customize your application server.

Custom container installations

If you use a custom container, you will find the cloudbees-core-cm.war or cloudbees-core-oc.war file in the deploy directory of your container. For example, /usr/local/jboss/server/default/deploy/cloudbees-core-cm.war would be the location for a default JBoss installation.

Microsoft Windows

To upgrade on Microsoft Windows servers, a new .zip must be downloaded from the downloads page and installed.

Post-upgrade notes

In case, JNLP agents (specifically for Microsoft Windows) are not able to connect, review the article Windows agent offline or unable to connect.

Review articles in our Best Practices and apply changes accordingly.

Installing CloudBees Analytics prerequisites

The next step is to install the prerequisites for CloudBees Analytics, which include the CloudBees CD/RO server, a webserver, a local agent, and a MariaDB database.

The artifact repository is not installed. Also, when installing the CloudBees CD/RO server, the CloudBees CD/RO plugins are not installed.

Use the steps in this section to install the prerequisite CloudBees Software Delivery Automation components needed for CloudBees Analytics. Review Before You Install CloudBees Software Delivery Automation before performing this procedure.

The built-in database is not supported in a clustered CloudBees Software Delivery Automation configuration.
  1. (Linux only) Enter the following command to make the installer file executable:

    chmod +x ./CloudBeesFlow-<version>
  2. Do one of the following to start the installation:

    • For Linux with root or sudo privileges or for Windows installations, double-click the installer file.

    • For Linux non-root/non-sudo installations, on a command line enter:

      ./CloudBeesFlow-<version> --nonRoot

      For this installation type, a warning about automatic server start-up with non-root/non-sudo installations appears. Click Yes to dismiss the warning.

    The install wizard welcome screen displays.

  3. Select one of the following

    • Install CloudBees Analytics prerequisites with built-in database: this option installs the built-in database, MariaDB, for use by the CloudBees Software Delivery Automation server.

    • Install CloudBees Analytics prerequisites without built-in database: this option does not install a database. After installation and during CloudBees Software Delivery Automation server startup, you are asked to configure a database.

    Select Next to continue. The Directories screen appears.

  4. Review Install directory and Data directory default locations; select Browse to specify different directory locations. Click Next to continue. The Server service account screen appears.

  5. Select the appropriate step for your platform and complete the information for the server service account.

    • Windows:

      • User Name: Enter the name of the user who will run the CloudBees Software Delivery Automation server, web server, and repository server services.

      • Password: Enter the password of the user who will run the CloudBees Software Delivery Automation server, web server, and repository server services.

      • Domain: Enter the domain name information for the user. Leave this field blank if this is a local user.

      • Use the local system account: Select this check box if you want the CloudBees Software Delivery Automation server, repository server, and web server services to run as the local Windows system account.

      • Use the same account for the agent service: Select this check box if you want the agent on the CloudBees Software Delivery Automation server machine to run as the same account.

        For security reasons in production environments, CloudBees recommends using a separate account for the agent service because the server account has permission to read the key file located here:

    • Linux: installation-directory/conf/passkey

    • Windows: installation-directory\conf\passkey

      The key file is used to decrypt passwords stored in CloudBees Software Delivery Automation. Using a different account for the agent service ensures that a process running on the agent cannot gain access to the key file.

    • Linux:

      • User Name: Enter the name of the user who owns the CloudBees Software Delivery Automation server, repository server, and web server processes.

      • Group Name: Enter the name of the group who owns the CloudBees Software Delivery Automation server, repository server, and web server processes.

      • Use the same account for the agent service: Select this check box if you want the agent on the CloudBees Software Delivery Automation server machine to run as the same account.

      Click Next to continue. The Agent Service Account screen appears.

    If you selected the Use the same account for the agent service check box on the previous screen, you will not see this screen.
  6. Select the appropriate step for your platform and complete the information for the agent service account.

    • Windows:

      • User Name: Enter the name of the user who will run the CloudBees Software Delivery Automation agent service.

        The user that the agent runs as must have permission to write to the $INSTALL_DIRECTORY/log directory.

      • Password: Enter the password of the user who will run the CloudBees Software Delivery Automation agent service.

      • Domain: Enter the domain name information for the user. For example, electric-cloud.com. Leave this field blank if this is a local user.

      • Use the local system account: Select this check box if you want the CloudBees Software Delivery Automation agent service to run as the local Windows system account.

        The local system account does not have access to network shares.
    • Linux:

      • User Name: Use this field to enter the name of the user who owns the CloudBees Software Delivery Automation agent process.

        The user/group that the agent runs as must have permission to write to the $INSTALL_DIRECTORY/log directory. If you specify root, click Yes when the following confirmation appears:

      • Group Name: Use this field to enter the name of the group that owns the CloudBees Software Delivery Automation agent process.

    Click Next to continue. The Ready to Install screen appears.

  7. Review the default settings and your service account selections. Use the Back button to change your service account selections if necessary.

  8. Review Send user data information. When checked, anonymized, aggregated usage information is sent to CloudBees. Uncheck if you do not want to participate. Click Next to continue.

    The installer displays a status bar to show the progress of the installation, which can take fifteen minutes. When the install process is complete, the Install Wizard Complete screen appears.

    The CloudBees Software Delivery Automation server automatically starts when the installation is complete.
  9. Select the Launch a web browser to login to CloudBees Software Delivery Automation check box if you want CloudBees Software Delivery Automation to open the login screen after installation is complete.

  10. Click Finish to close the wizard.

  11. For non-root/non-sudo Linux installations, configure autostart for the CloudBees Software Delivery Automation services.

If you opted for installation without the built-in database, you are prompted on the sign-in page to configure an external database during CloudBees CD/RO server startup. See External database configuration for further information.

Installing CloudBees Analytics

The next step is to install CloudBees Analytics on a separate server.

Start the installation by following the steps for using the CloudBees Analytics UI installer.