Pre-installation checklist for traditional platforms

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, refer to 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 Configure an external database.

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, refer to 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:

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

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

Uninstall the CloudBees Analytics server from the system.
Clean up data, logs, and any configuration files from the CloudBees CD/RO data directory on the system.
Install the other CloudBees CD/RO components on the system as needed.
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.

Required locale system variables

CloudBees CD/RO servers require a UTF-8 charset to function properly. In your environment, a system locale with a UTF-8 charset must be either configured by default, or the system locale en_US.utf8 must be available for use. If the UTF-8 charset or system locale en_US.utf8 are not available in the environment, CloudBees CD/RO installers will not install the server component, and return the error message:

Unable to detect a usable utf8 system locale, which is required for the server service.▼

In Silent installation arguments, there is a method to disable checks for the UTF-8 charset in the current locale and the availability of en_US.utf8 system locale. However, disabling this check will likely cause errors when processing data with multibyte characters. This option should only be used with guidance from CloudBees Support.

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.

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, refer to Installation user requirements.

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 configuration installation

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. The following diagram shows an example of a remote web server architecture configuration.

Figure 1. Remote web server configuration

In this example for a remote web server configuration:

There are web servers at each site.
The database and CloudBees CD/RO server is located at your headquarters.
CloudBees CD/RO agents exist at each site.

Central web server and a remote web server at each site

You should consider installing multiple web servers for different locations in your organization to help handle user web traffic. CloudBees CD/RO supports multiple workspaces, including those co-located on agents that use them. In this architecture, step log files are created locally so even the largest log files can be captured without a performance penalty.
You can view the step log files remotely from the web UI, but performance decreases if the files must be retrieved across the WAN. This means that remote users will experience the penalty when the web server retrieves the step log file contents and when the contents are sent back across the WAN to the browser.
To minimize these performance issues, install one central CloudBees CD/RO server, and then install a CloudBees CD/RO web server at each remote site. The remote web servers should be co-located with the remote agents and workspaces so remote users can log in through their local web server. Any operations initiated from the remote location, including running jobs, are completed by the central CloudBees CD/RO server.
In this configuration, job data is retrieved from the central server when a remote user views the Job Details page. If the job is using a workspace at the remote user’s site, the links to all step log files refer to local paths.
Also, in this configuration, the log files are accessed only by the remote web server’s agent and not the CloudBees CD/RO server. This eliminates both trips across the WAN, which improves performance. The CloudBees CD/RO web server reads the log file locally (via its local agent) and then displays the page to the user whose browser is also on the same side of the WAN.

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, refer to 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 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, refer to Configure universal access to the plugins directory.

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

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 value displayed is less than 262144, add this line to the /etc/sysctl.conf file:
```
vm.max_map_count = 262144▼
```
Apply the settings by entering the following command using the root account:
```
$ sudo /sbin/sysctl -p▼
```
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, refer to https://www.elastic.co/.

Checking the maximum number of open files descriptors setting

Run the following command as the user that will be used for the non-root installation:
```
$ ulimit -n
65536▼
```
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.
Log back into the system.
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, refer to https://www.elastic.co.

Checking the number of threads setting

Run the following command as the user to be used for non-root installation by entering the following command:
```
$ ulimit -u
4096▼
```
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.
Log back into the system.
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▼
```

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

For more information, refer to https://www.elastic.co.