Before you install CloudBees CD/RO

9 minute readReference

Review the following information before attempting to install any CloudBees CD/RO software.

Linux and Windows CloudBees CD/RO installations

Platform setup prerequisite

Make sure you have completed any prerequisite platform setup. For details, see CloudBees supported platforms.

Local drive requirement

You must install CloudBees CD/RO on a local drive. CloudBees does not support installing the CloudBees CD/RO server on a network volume.

Installation order

CloudBees recommends installing the CloudBees CD/RO server before installing remote agents or web servers.

Built-in database versus alternate databases

CloudBees CD/RO ships with a demo license, which limits the software to two concurrent job steps and the CloudBees CD/RO-provided built-in database. Running CloudBees CD/RO on a single machine with the demo license is not recommended for a production environment. Additionally, the built-in database is not supported in a clustered CloudBees CD/RO configuration.

In a production configuration, connect CloudBees CD/RO to a database. If CloudBees CD/RO is installed with the built-in database, you can reconfigure it to use an external database at any time. For more information and configuration instructions, refer to External database configuration.

Using an external database requires a CloudBees CD/RO enterprise license. You must configure an external database at the same time as you install your enterprise license to prevent error messages about an unsupported configuration or a license requirement.

Java runtime environment bitness

When you install a 64-bit machine, the 64-bit version of the Java Runtime Environment is installed automatically.

Specifying a remote CloudBees CD/RO server

When installing an agent, repository server, or web server, you can enter information for a remote CloudBees CD/RO server. That information is used to discover the server’s plugins directory and set it so that the local installation is in sync with the remote CloudBees CD/RO server.

During an agent installation, you can create a resource object on the server automatically. During a repository installation, you can create a repository object on the server automatically.

Clustered CloudBees CD/RO configurations

If you plan to use a clustered CloudBees CD/RO configuration, see Clustering for additional requirements and considerations.

Clustered CloudBees Analytics server configurations

For details about the overall steps for installing CloudBees Analytics on a group of servers to create a CloudBees Analytics server cluster, refer to Installing the CloudBees Analytics Server in Cluster Mode.

Running the CloudBees Analytics server on a system with other CloudBees CD/RO components

For a production environment, CloudBees recommends that you install the CloudBees Analytics server on a system other than systems running other CloudBees CD/RO components (such as the CloudBees CD/RO server, web server, repository server, or agent). If you must install it on the same system (such as for testing or other non-production or trial-basis situations), use one of the following installation processes.

If you have not yet installed the CloudBees Analytics server on a system:

  1. Install the other CloudBees CD/RO components on the system as needed.

  2. Install the CloudBees Analytics server on the system.

If you have already installed the CloudBees Analytics server on a system:

  1. Uninstall the CloudBees Analytics server from the system.

  2. Clean up data, logs, and any configuration files from the CloudBees CD/RO data directory on the system.

  3. Install the other CloudBees CD/RO components on the system as needed.

  4. Reinstall the CloudBees Analytics server on the system.

Linux CloudBees CD/RO installations

Review the following information before installing CloudBees CD/RO on a Linux machine.

umask and file permission requirements

The CloudBees CD/RO installer sets the required umask and permissions on all CloudBees CD/RO directories and files as follows:

  • umask: 0022

  • Permissions for owner of CloudBees files: 0644

  • Executable file permissions: 0755

To avoid unexpected errors in functionality, do not change these values.

Installation mode without the x window system

If the X Window System is not running or not available, the Linux user interface installer runs in interactive command-line mode.

Pseudo 64-bit agent-only installers (linux)

The 32-bit agent installer is a 32-bit executable that does not check if the machine has the required 32-bit compatibility libraries during the installation session .

IMPORTANT:

When installing CloudBees CD/RO on RHEL 6.x: For the 32-bit agent-only installer or the “pseudo” 64-bit agent-only installer on unsupported platforms or without an internet connection, you must install certain 32-bit libraries that were omitted by Red Hat. Otherwise, the installer exits because it cannot find those libraries. No error prompt is displayed, and the log file does not contain the error. To install the libraries, run the following commands:

  • yum install libstdc++.i686 —Without this command, the CloudBees CD/RO Apache server will not start, and the installer silently fails for any type of CloudBees CD/RO installation.

  • yum install libuuid.i686 —Required if your CloudBees CD/RO installation includes an Apache server. If you are installing CloudBees CD/RO agents only without Apache, you do not need this command on agent machines.

  • yum install nss-pam-ldapd*.i686 —Installs 32-bit NSS packages if using an LDAP account for ownership of the server, web, and repository services. Without this command, the CloudBees CD/RO Apache server fails to start.

32-bit libraries are not required for the “pure” 64-bit full installer or the “pure” 64-bit agent-only installer.

IMPORTANT:

When installing CloudBees CD/RO on Ubuntu versions listed below: For the 32-bit agent-only installer or the “pseudo” 64-bit agent-only installer on unsupported platforms or without an internet connection, you must install certain 32-bit libraries that were omitted by Ubuntu. Otherwise, the installer exits because it cannot find those libraries. No error prompt is displayed, and the log file does not contain the error. To install the libraries, run the following commands:

  • On Ubuntu 14.04, enter: sudo apt-get update sudo dpkg --add-architecture i386 sudo apt-get update sudo apt-get install lib32bz2-1.0 sudo apt-get update sudo apt-get install libuuid1:i386

  • On Ubuntu 18.04 or 16.04, enter these commands: sudo apt-get update sudo dpkg --add-architecture i386 sudo apt-get update sudo apt-get install libbz2-1.0:i386 sudo apt-get update sudo apt-get install libuuid1:i386

  • On Ubuntu 15.04, enter sudo apt-get update && sudo apt-get install lib32z1 lib32ncurses5 libbz2-1.0:i386.

  • If you will use an LDAP account for ownership of the server, web, and repository services with 64-bit Ubuntu, you must run sudo apt-get update && sudo apt-get install libnss-ldap:i386. This command installs 32-bit NSS packages, which ensures that the CloudBees CD/RO Apache server starts.

32-bit libraries are not required for the “pure” 64-bit full installer or the “pure” 64-bit agent-only installer.

Unsupported linux platforms

For platforms such as Debian, CentOS, or Fedora, install the following 32-bit libraries before installing CloudBees CD/RO. They are required by the CloudBees CD/RO installation executable file. CloudBees recommends installing all of these libraries on your 64-bit machines.

  • libstdc++.i686: If you do not install this, the CloudBees CD/RO Apache server will not start, and the installer silently fails for any type of CloudBees CD/RO installation.

  • libuuid.i686:Install this if you are performing a CloudBees CD/RO installation that includes an Apache server. If you are installing CloudBees CD/RO agents only, without a web server, you do not need to run this command on each agent machine.

  • nss-pam-ldapd*.i686: Install the 32-bit NSS packages if you are using an LDAP account for ownership of the server, web, or repository services. If you do not run this command, the CloudBees CD/RO Apache server fails to start.

Installing or uninstalling without root/sudo or administrator privileges

Certain CloudBees CD/RO installers allow you to perform installations as a non-root user or a user without sudo privileges. To determine whether a particular installer has an option to run in this mode, see Installing Without Root/sudo or Administrator Privileges .

The installer writes installation data to the home directory of the user who invoked the installer. By default, the installer checks whether the HOME environment variable is defined and points to a writeable directory. The installer will read this data during subsequent upgrades or uninstallations.

Therefore, if you anticipate a same-system future upgrade (or uninstallation), you must ensure that you have a home directory before invoking the installer. If you do not plan to upgrade, you must use the --skipCheckUserHomeDirectory installer argument to ensure that the installer finishes successfully.

Remote CloudBees CD/RO web server installation prerequisites

A remote web server configuration helps prevent network latency. If you have multiple sites, CloudBees CD/RO can be configured in numerous ways to help you work more efficiently. For details about the architecture for this configuration as well as a discussion of the benefits of using a central web server and web servers at each remote site, refer to Remote Web Server Configuration .

Web server platform and memory requirements

You can install a CloudBees CD/RO web server on any Windows or Linux platform suitable for installing the CloudBees CD/RO server. For platform requirements, see Platform notes .

The memory settings for the agent on each web server machine must be higher than the default agent settings. More memory is typically needed for streaming large log files and so on. For agent memory requirements and instructions for configuring agent memory, refer to the KBEC-00248 - Agent Memory Configuration

Local agent installation requirement for web server machines

Every local or remote web server requires a local agent (that is, an agent on that machine) to be present to enable communication with the CloudBees CD/RO server or other agents. Whenever any web server is installed, a local agent is also installed because:

  • Each web server delegates all requests to the CloudBees CD/RO server to its local agent, which then knows how to forward the request to the CloudBees CD/RO server.

  • If a web server must render the step log from a remote agent to the browser, it delegates the request to its local agent. The local agent then asks the CloudBees CD/RO server for a route to reach the remote agent and the location of the step log, so that the step log can then be streamed from the remote agent.

You should not use these local agents to run jobs.

Plugins directory accessibility requirement for web server machines

A plugin is a collection of one or more features or a third-party integration or tool that can be added to CloudBees CD/RO. The CloudBees CD/RO server installs all plugins into a configurable location named the plugins directory. This directory must be readable by the web server and any agents that need access to the content of one or more plugins.

There are two ways to make the plugins directory readable by the web server. You can configure the CloudBees CD/RO server and web servers to point to a central network location, or you can replicate the contents of the plugins directory on remote web servers.

CloudBees strongly recommends that all server machines in a remote web server configuration be able to access a common plugins directory in a central network location. This avoids the overhead of managing multiple plugins directories. For details, see Configuring Universal Access for a Network Location

Requirements for non-root or Docker CloudBees Analytics installations on Linux platforms

You typically perform a CloudBees Analytics installation as root, which gives the installer all the required permissions required to change certain operating system settings as needed. If you will be performing an installation as a non-root user or in a Docker environment, you must change these settings manually.

Checking the virtual memory areas setting

  1. Run the following command as the user to be used for non-root installation:

    $ /sbin/sysctl vm.max_map_count vm.max_map_count = 262144
  2. If the value displayed is less than 262144, add this line to the /etc/sysctl.conf file:

    vm.max_map_count = 262144
  3. Apply the settings by entering the following command using the root account:

    $ sudo /sbin/sysctl -p
  4. Verify that the following variable has the required value by entering:

    $ /sbin/sysctl vm.max_map_count vm.max_map_count = 262144

Run the following command as the user to be used for non-root installation:

$ /sbin/sysctl vm.max_map_count vm.max_map_count = 262144

If the retrieved value is less than 262144, then this environment is not compatible with CloudBees Analytics Server. The setting must be increased at least to this value. It can be done by these steps:

Add this line to the /etc/sysctl.conf file:

vm.max_map_count = 262144

Apply the settings by this command using the root account:

$ sudo /sbin/sysctl -p

Verify that the following variable has the required value:

$ /sbin/sysctl vm.max_map_count vm.max_map_count = 262144

For more information, see https://www.elastic.co/.

Checking the maximum number of open files descriptors setting

  1. Run the following command as the user that will be used for the non-root installation:

    $ ulimit -n 65536
  2. If the value displayed is less than 65536, add the following lines to the /etc/security/limits.conf file:

    * soft nofile 65536 * hard nofile 65536

    These settings will change the values for all users in system. To change the settings only for the user to be used for CloudBees Analytics server installation, replace the asterisks in the above lines by that username.

  3. Log back into the system.

  4. Verify that the setting has the required value by entering the following command:

    $ ulimit -n 65536

Run the following command as the user that will be used for the non-root installation:

$ ulimit -n 65536

If the retrieved value is less than 65536, then this environment is not compatible with the CloudBees Analytics server. The setting must be increased at least to this value. It can be done by these steps:

Add the following lines to the /etc/security/limits.conf file:

* soft nofile 65536 * hard nofile 65536

These settings will change the values for all users in system. To change the settings only for the user to be used for CloudBees Analytics server installation, replace the asterisks in the above lines by that username.

Log back into the system.

Verify that the setting has the required value:

$ ulimit -n 65536

For more information, see https://www.elastic.co.

Checking the number of threads setting

  1. Run the following command as the user to be used for non-root installation by entering the following command:

    $ ulimit -u 4096
  2. If the value displayed is less than 4096, add the following lines to the /etc/security/limits.conf file:

    * soft nproc 4096 * hard nproc 4096

    These settings will change the value for all users in the system. To change the settings only for the user to be used for CloudBees Analytics server installation, replace the asterisks in the above lines by that username.

  3. Log back into the system.

  4. Verify that the setting has the required value by entering the following command:

    $ ulimit -u 4096

Run the following command as the user to be used for non-root installation:

$ ulimit -u 4096

If the retrieved value is less than 4096, then this environment is not compatible with the CloudBees Analytics server. The setting must be increased at least to this value. It can be done by these steps:

Add the following lines to the /etc/security/limits.conf file:

* soft nproc 4096 * hard nproc 4096

These settings will change the value for all users in the system. To change the settings only for one user which will be used for CloudBees Analytics Server installation replace asterisks in the above lines by needed username.

Log back into the system.

Verify that the setting has the required value:

$ ulimit -u 4096
Note: If the login shell is the dash shell, then you must use the ulimit -p command instead to check this setting.

For more information, see https://www.elastic.co.