Before You Install CloudBees Flow

10 minute read

Review the following information before attempting to install any CloudBees Flow software.

Linux and Windows CloudBees Flow 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 Flow on a local drive. CloudBees does not support installing the CloudBees Flow server on a network volume.

Installation Order

CloudBees recommends installing the CloudBees Flow server before installing remote agents or web servers.

Built-In Database Versus Alternate Databases

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

In a production configuration, connect CloudBees Flow to a database. If CloudBees Flow is installed with the built-in database, you can reconfigure it to use an external database at any time. For a list of alternate databases supported by CloudBees Flow, see Supported Alternate Databases. For more information and configuration instructions, see External Database Configuration.

Using an external database requires a CloudBees Flow 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 Flow Server

When installing an agent, repository server, or web server, you can enter information for a remote CloudBees Flow 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 Flow 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 Flow Configurations

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

Clustered DevOps Insight Server Configurations

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

Running the DevOps Insight Server on a System with Other CloudBees Flow Components

For a production environment, CloudBees recommends that you install the DevOps Insight server on a system other than systems running other CloudBees Flow components (such as the CloudBees Flow 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 Flow DevOps Insight server on a system:

  1. Install the other CloudBees Flow components on the system as needed.

  2. Install the CloudBees Flow DevOps Insight server on the system.

If you have already installed the DevOps Insight server on a system:

  1. Uninstall the CloudBees Flow DevOps Insight server from the system.

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

  3. Install the other CloudBees Flow components on the system as needed.

  4. Reinstall the CloudBees Flow DevOps Insight server on the system.

Linux CloudBees Flow Installations

Review the following information before installing CloudBees Flow on a Linux machine.

umask and File Permission Requirements

The CloudBees Flow installer sets the required umask and permissions on all CloudBees Flow 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 Flow 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 Flow Apache server will not start, and the installer silently fails for any type of CloudBees Flow installation.

  • yum install libuuid.i686 —Required if your CloudBees Flow installation includes an Apache server. If you are installing CloudBees Flow 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 Flow 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 Flow 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 Flow 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 Flow. They are required by the CloudBees Flow 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 Flow Apache server will not start, and the installer silently fails for any type of CloudBees Flow installation.

  • libuuid.i686:Install this if you are performing a CloudBees Flow installation that includes an Apache server. If you are installing CloudBees Flow 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 Flow Apache server fails to start.

Installing or Uninstalling Without Root/sudo or Administrator Privileges

Certain CloudBees Flow 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 Flow Web Server Installation Prerequisites

A remote web server configuration helps prevent network latency. If you have multiple sites, CloudBees Flow 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, see Remote Web Server Configuration on page 1 .

Web Server Platform and Memory Requirements

You can install a CloudBees Flow web server on any Windows or Linux platform suitable for installing the CloudBees Flow 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, see 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 Flow 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 Flow server to its local agent, which then knows how to forward the request to the CloudBees Flow 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 Flow 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 Flow. The CloudBees Flow 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 Flow 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 DevOps Insight Installations on Linux Platforms

You typically perform a DevOps Insight ) 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 ElecteicFlow DevOps Insight 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 DevOps Insight 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 DevOps Insight 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 Flow DevOps Insight 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 DevOps Insight 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 DevOps Insight 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 Flow DevOps Insight 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.