Install a custom configuration

This page covers how to install CloudBees CD/RO using the GUI-based Advanced option of Windows and Linux full installers.

To perform a GUI-based installation for Linux, you must have a graphical environment installed. If your Linux environment does not have a graphical environment installed, refer to the corresponding interactive Linux command-line option to continue installation.

The Advanced option allows you to install any combination of the following CloudBees CD/RO components on the host machine with the option to configure custom settings:

Server
Web server
Repository server
Built-in database or custom database
Agent
CloudBees CD/RO tools (Required)

The built-in database does not support production or clustered environments.

Before you start

The following are important knowledge prerequisites to review before starting this procedure:

CloudBees recommends reviewing the following resources before installation:

CloudBees strongly suggests to use the Advanced option when configuring production environments. For more information, refer to Installation types.

For production environments, CloudBees recommends installing each CloudBees CD/RO component on separate machines using the Advanced installation option.

Additionally, there are specific agent security recommendations available at Agent security recommendations.

Perform an Advanced installation

To perform an Advanced installation:

If you have not already done so, download the full installer file. To download this version, select your required installer:
- Windows full installer: 2024.12.0.177508
- Linux full installer: 2024.12.0.177508
For more details on installers, refer to Install CloudBees CD/RO on traditional platforms.

For legacy installer downloads, navigate to CloudBees CD/RO downloads.
Start the installer:
- Windows:
  Windows installers
  On Windows, an Administrator user is required to install CloudBees CD/RO. For more information about required user privileges, refer to Windows services user permissions.
  
  Navigate to the directory where you downloaded the CloudBees CD/RO installer.
  
  Double-click the installer. This starts the installer in the GUI-based installation mode.
- Linux:
  Linux installers
  Navigate to the directory where you downloaded the CloudBees CD/RO installer.
  
  Enter the following command to make the installer file executable:
  
  Command
  Current version
  
  chmod +x CloudBeesFlow-x64-<version>
  ▼
  
  chmod +x CloudBeesFlow-x64-2024.12.0.177508
  ▼
  
  Start the installation:
  
  For more information about required user privileges, refer to Linux services user permissions.
  
  For root or sudo installations:
  
  Root or sudo procedures
  
  Navigate to the directory where you downloaded CloudBees CD/RO.
  
  Double-click the installer. This starts the installer in the GUI-based installation mode.
  
  For non-root/non-sudo installations, from the terminal, run:
  
  Non-root/non-sudo procedures
  
  Command
  Current version
  
  ./CloudBeesFlow-x64-<version> --nonRoot
  ▼
  
  ./CloudBeesFlow-x64-2024.12.0.177508 --nonRoot
  ▼
  
  A warning about automatic server start-up with non-root/non- sudo installations appears. Select Yes to dismiss the warning.
Select Advanced: Install CloudBees CD/RO with a custom configuration option, and select Next to continue. The Components screen appears.

On the Components screen, all options are selected by default. Clear the checkboxes for components you do not want to install.

When finished, select Next to continue.

Available component options and descriptions:

Server: Installs a CloudBees CD/RO server.

If you clear this checkbox, the Remote CloudBees CD/RO Server screen appears later (shown below).
Database: Installs the built-in database.
- Uncheck this box for production environments or if you plan to install an external database.
  
  The built-in database does not support production or clustered environments.

Web server: Installs a CloudBees CD/RO web server.

If you select this option, an agent is also required on this machine, and is automatically installed.

You should not use this local agent to run jobs. It is required for internal usage, and running additional jobs on it significantly decreases performance.

Repository: Installs a CloudBees CD/RO repository server.

If you select this option, an agent is also required on this machine, and is automatically installed.

You should not use this local agent to run jobs. It is required for internal usage, and running additional jobs on it significantly decreases performance.

Agent: Installs CloudBees CD/RO agent software.
CloudBees CD/RO Tools: Installs command-line utilities used to access CloudBees CD/RO servers.
- To install only CloudBees CD/RO Tools, clear all the checkboxes.
  
  All CloudBees CD/RO components require CloudBees CD/RO Tools, and selecting any other component also automatically installs CloudBees CD/RO Tools.

Depending on the components you selected, the following descriptions may not appear in the order listed here.

The Directories screen appears. Specify the installation and data directories.
- Select Next to install CloudBees CD/RO using the default directories.
- Select Browse to specify different directory locations.
  1. Select Next to continue.
If you are installing a CloudBees CD/RO, web, or repository server, the Ports screen appears. Select Next to install CloudBees CD/RO using the default ports, or specify custom port values.
1. Select Next to continue.

If you are installing a web server, the Web server URL configuration screen appears:

Configure the web server URL:

Host name: Enter the URL users must enter in their browser to access the CloudBees CD/RO web server.

Default UI: Determines if the Flow UI or the Commander UI opens by default when users browse to https://<host-name-url> without appending /flow or /commander to the end of the URL.

For example, if you select Flow, the Flow UI opens by default if you browse to https://my-cdro-web-host or https://my-cdro-web-host/flow.

You can reconfigure the Default UI behavior post-installation by using the ecconfigure --webDefaultUI option. For details, refer to the ecconfigure section in CloudBees CD/RO utility and tools.

Select Next to continue.

If you cleared the Server checkbox on the Components page, the Remote CloudBees CD/RO server screen appears. Configure the following:

Configure the remote CloudBees CD/RO server:

Server host name: Enter the name of the remote CloudBees CD/RO server that will communicate with this web server.

If the remote server is using a non-default HTTPS port, you must specify the Server Host Name as <host>:<port>. If you do not specify a port, HTTPS port 8443 is assumed (the same as the CloudBees CD/RO server default port).

CloudBees CD/RO Username: Enter the name of a CloudBees CD/RO server user with sufficient privileges to create a resource. This field defaults to the CloudBees CD/RO-supplied admin user.
Password: Enter the password for the user entered in CloudBees CD/RO Username.

Discover the plugins directory: Select this checkbox to allow the web server to have access to the shared plugins directory. For web server agents to access the plugins directory, which includes collections of features, third-party integrations, and third-party tools, you must select this option.

The plugins directory on the CloudBees CD/RO server must be shared before the web server machine can discover it. For more information, refer to Configure universal access to the plugins directory.

Create a resource: Select this checkbox if you want to create a resource on the remote CloudBees CD/RO server for the web server you are installing.

Trusted: Select this checkbox to restrict this web server to one CloudBees CD/RO server.

If Trusted is selected, the web server will not respond to incoming communication from any other CloudBees CD/RO server. This is useful when you want to create a secure production environment, but generally not needed for test or development systems.

Resource name: Enter the name of the resource to use.
Workspace Name: Enter the name of the workspace you would like to use for the web server.
Create a repository: Select to create an artifact repository on this machine.
Repository name: Enter the name of the artifact repository to create.
Create in default zone: Select this checkbox to create the agent in the default zone.
Agent Gateway URL: Enter the URL of the gateway used to communicate with the CloudBees CD/RO server.

This field is only available for use when the Create in default zone checkbox is cleared.
Zone Name: Enter the name of the zone used during remote agent and/or remote repository creation.

This field is only available for use when the Create in default zone checkbox is cleared.

Select Next to continue.

If you are installing a CloudBees CD/RO, web, or repository server, the Server service account screen appears. Follow the platform-specific instruction below:

Windows:

Configure Windows server service account:

Username: Enter the username of a host user to run the CloudBees CD/RO server, web server, and repository server services.
Password : Enter the password of the user entered in Username.
Domain: Enter the domain name information for the user. For example, electric-cloud.com.

Leave this field blank to run the agent as a local user.

Use the local system account: Select this checkbox if you want the CloudBees CD/RO server, repository server, and web server services to run as the Windows local system account.

The Windows local system account cannot access network resources, such as shared file systems used for plugins or workspaces. Therefore, do not use this option for a clustered server deployment, which requires a shared file system for plugins.

This option is typically used only for installing agents on numerous machines, which normally requires creating a new account on each machine.

Use the same account for the agent service: Select this checkbox if you want the agent on the CloudBees CD/RO server machine to run as the same account.

For security, CloudBees recommends not installing agents on the server host or giving any agents access to the server file system. Doing so may give an agent access to sensitive files such as the server passkey, database configuration, and other system resources allotted to CloudBees CD/RO.

If the agent is installed on the server host or given access to the server file system (such as for short-lived development and testing), CloudBees strongly recommends using separate users for server and agent services. This helps prevent the agent from accessing sensitive files. Using the same user for both services gives an agent the same access permissions as the server user.

Additionally, CloudBees strongly recommends not running agents as sudo or ROOT users in production, or long-lived development and testing environments. Running agents with these privileges poses significant security risks, as they have unlimited ability to execute operations which can be used to access any file on the agent host, or modify the configuration of that host.

Assign CloudBees CD/RO agent users only the necessary privileges to perform their functions, following the Principle of Least Privilege (PoLP). This helps to prevent permission escalation and data exposure should an agent become compromised.

For more information on how to mitigate agent security risks, refer to Agent security recommendations.

Select Next to continue:

If you selected Use the same account for the agent service, the Ready to install screen appears.
If you did not select Use the same account for the agent service, the Agent service account screen appears.

Linux:

Configure Linux server service account:

Username: Enter the username of a host user to run the CloudBees CD/RO server, web server, and repository server services.
Group name: Enter the system group name for the user entered in Username.

Use the same account for the agent service: Select this checkbox to use the same account entered for the server to run agent services.

For more information on how to mitigate agent security risks, refer to Agent security recommendations.

Select Next to continue:

If you selected to use the same user the server and agent, the Security settings screen appears.
If you did not select Use the same account for the agent service, the Agent service account screen appears.

If you are installing an agent using a separate user, the Agent service account screen appears. Follow the platform-specific instructions below:

Windows:

Configure Windows agent service account:

Username: Enter the username of a host user to run the CloudBees CD/RO server, web server, and repository server services.

The user the agent runs as must have permission to write to the $INSTALL_DIRECTORY\log directory.
Password: Enter the password of the user entered in Username.
Domain: Enter the user’s domain name, such as electric-cloud.com. Leave this field blank if this is a local user.

Use the local system account: Select this checkbox if you want the CloudBees CD/RO agent service to run as the local Windows system account.

This option is typically used only for installing agents on numerous machines, which normally requires creating a new account on each machine.

Select Next. The Ready to install screen appears.

Linux:
Configure Linux agent service account:
- Username: Enter the username of a host user to run CloudBees CD/RO agent processes.
  
  The user/group the agent runs as must have permission to write to the $INSTALL_DIRECTORY/log directory.
  
  If you specify root, select Yes when confirmation appears.
- Group name: Enter the system group name for the user entered in Username.
Select Next. The Security settings screen appears.

(Linux only) On the Security settings screen, you can configure the SSL/TLS protocols for CloudBees CD/RO component connections using HTTPS. The possible values are any combination of TLSv1, TLSv1.1, TLSv1.2, and SSLv2Hello.

You must select at least one protocol for each connection.
Default security setting descriptions:
The default security configurations are as follows:
- First-time CloudBees CD/RO installations: TLSv1, TLSv1.1, and TLSv1.2 are enabled
- Existing CloudBees CD/RO installations: TLSv1, TLSv1.1, TLSv1.2, and SSLv2Hello are enabled
The default for upgrades from version 8.5 and newer versions is to inherit the settings from the existing installation being upgraded.

CloudBees recommends removing the SSL 2.0 Client Hello or SSLv2Hello protocol from your security configurations for all components.
- Upgrade agents older that fall into this category for security reasons:
  
  Windows, Linux: 6.0.3 or older; 6.2 or older
  
  Mac OS: 8.4 or older
- If this warning appears on the Automation Platform UI:
  
  Note: We recommend removing `SSL 2.0 Client Hello` format from server configuration and upgrade older agents as indicated on the Cloud/Resources Page to avoid security risk.
  ▼
  
  then enter the following command on the CloudBees CD/RO server:
  
  $ ecconfigure --serverTLSEnabledProtocol=TLSv1.2
  ▼
1. After completing the configuration, select Next. The Ready to install screen appears.

On the Ready to install screen, review the settings and your service account configurations.
- If any information is incorrect, use the Back button to navigate back through the configurations.

Select whether to send usage data. If you do not wish to participate, clear the Help improve CloudBees CD/RO? checkbox.

If you select to send usage data, you can disable sending data at anytime by setting Server settings System setttings Send Usage Data to Disabled. This can be updated without reinstalling or upgrading CloudBees CD/RO.

Select Next to install CloudBees CD/RO the selected components.

The installer displays a status bar to show the progress of the installation. If you installed the CloudBees CD/RO web server, when the installation finishes, the Installation complete screen appears:

Select the Launch a web browser to log in to CloudBees CD/RO checkbox if you want CloudBees CD/RO to open when you exit the wizard.
Select Finish to close the wizard.

The default sign in credentials are:

Username: admin
Password: changeme

On your first sign in, CloudBees strongly suggests to immediately change the default password. To do so:

Log into CloudBees CD/RO using the default credentials.
Navigate to Administration Users.
From the Users list, select admin. The Edit User window opens.
In the Current Password field, enter the default password.
In the New Password field, enter a new password.
Confirm your new password by entering it again in the Retype Password field.
Select OK.
Log out of CloudBees CD/RO, and then log back in using your new password.

For more information on sign in options, refer to Sign in to CloudBees CD/RO.

Configure autostart for non-root environments

For installations performed as a Windows Administrator or with Linux root or sudo privileges, CloudBees CD/RO components start automatically upon completing the installation and during system boot. However, for non-root/non-sudo Linux installations CloudBees CD/RO components do not have the permissions to start automatically.

To configure autostart for non-root or non-sudo Linux installations of CloudBees CD/RO components, refer to Configure autostart for non-root/non-sudo Linux installations.