Basic install

This topic describes how to perform a basic installation of Deploy - either a simple setup with the default configuration, or a manual setup in which you can choose specific options. If you are installing Deploy in a production-ready environment that includes options like a separate, clustered database server, load balancing for your Deploy servers, an active/hot-standby cluster configuration for your Deploy servers, and other security, monitoring, and performance considerations, see Production install.

After you install the Deploy server, you can optionally:

• Configure Deploy to run as a background Daemon or service.
• Install the Deploy CLI on a remote computer and connect it to the server, enabling you to control and administer Deploy features. For more information, see Install the Deploy CLI.

Choosing the correct setup for your requirements

Type	Possible Configurations	Recommendations	Documentation
Basic installation	Install and run Deploy on a single instance	Recommended if you don't have a high number of concurrent deployments	1. Basic setup
High Scale setup	Setup Deploy to run on one master node and one worker node	Same as basic setup. But provides the flexibility of adding more workers later.	1. Basic Install 2. Add, start, and use workers
	Setup Deploy to run on one master and multiple worker nodes	Adds scalability to the basic setup. You can use this setup to run multiple deployment tasks in parallel. Add as many workers as you need to make it scalable.	1. Basic Install 2. Add, start, and use workers 3. Configure Deploy to use multiple workers
High availability (HA) Setup	Setup Deploy to run on one active master and one or more master nodes in standby	Active—Hot-Standby setup provides scalability with a failover mechanism. You can setup one node to be active and all other nodes to be in standby, waiting to be activated when the active node fails. This setup comes with restrictions and is not recommended for HA.	1. Set up an Active—Hot-Standby Cluster
	Setup Deploy to run on multiple master and worker nodes	Active-Active setup adds high availability and high scalability to the basic setup with multiple master and worker nodes.	1. Set up an Active-Active Cluster 2. Add, start, and use workers 3. Configure Deploy to use multiple workers
		Operator-based cluster setup allows you to use the Active-Active setup with the advantages of Kubernetes.	1. Plan Your Installation or Upgrade

Other recommendations:

• You can use Satellites with any of these setups for more flexibility.
• In a multi-master HA setup, installing Central Configuration as a microservice makes it easier to manage.

Verify system requirements

Before installing Deploy, ensure that your system meets the minimum server, network, and hard disk requirements. For more information, see Requirements for installing Deploy

Tip: If you are upgrading a previously installed version of Deploy, refer to Upgrade Deploy.

Extract the Deploy server archive

Windows

1. Create a folder for installation at any location. This is the location from where you will run the installation tasks.
2. Download the Deploy server archive (ZIP file) from the Deploy/Release Software Distribution site (requires customer log-in).
3. Extract the Deploy server archive to the directory.

To extract the Deploy server archive:

1. Create a dedicated non-root user called xl-deploy. This ensures that you can lock down the operating system and prevent accidental privilege escalations.
2. Create an installation directory such as /opt/xebialabs/xl-deploy or C:\Program Files\Deploy.
3. Download the Deploy server archive (ZIP file) from the Deploy/Release Software Distribution site (requires customer log-in).
4. Extract the downloaded Deploy server archive to the installation directory.
5. Change the ownership of the extracted files to xl-deploy and grant the user read access to the installation directory.
6. Grant the xl-deploy user write access to the /opt/xebialabs/xl-deploy-<version>-server/conf and /opt/xebialabs/xl-deploy-<version>-server/log directories.

Set up the Deploy Database

You must set up a database for the Deploy to store data. Create and configure an empty database before you start Deploy installation. During the installation, Deploy creates the database schema on the database you created. Optionally, you can have separate database for the operational and reporting databases. For more information about creating two separate databases, see Separate Databases for Reporting and Repository in Deploy.

Use a industrial-grade external database server, for example PostgreSQL, for production use. For more information, see Configure the Database and Artifacts Repository.

Install the license

If you received a Deploy license key by email, you will be prompted to enter it after you install and start Deploy.

If you do not have a Deploy license key, you can download a license file (deployit-license.lic) from the Deploy/Release Software Distribution site (requires customer log-in). Place the license file in the conf directory before you install Deploy. Ensure that you do not modify the license file.

For information about the Deploy license, see Deploy licensing.

Run the server setup wizard

To install the Deploy server, go to a command line or terminal window and execute the appropriate command to start the setup wizard:

Important: After the initial run, passwords in the configuration file will be encrypted and replaced with the base 64-encoded encrypted values.

Operating system	Command
Microsoft Windows	run.cmd -setup
Unix-based systems	run.sh -setup

To stop the setup wizard at any time, enter exitsetup. All changes to the configuration will be discarded.

Select a setup method

The setup wizard shows the welcome message. You can:

• Answer yes (or press ENTER) to install Deploy with a default configuration. This method makes it easy for you to quickly get started with Deploy. See Simple setup for more information.
• Answer no to install Deploy manually. This method gives you explicit control over all Deploy settings. See Manual setup for more information.

Note: If you have installed Deploy in the same location before, the setup wizard will ask you if you want to edit the existing configuration or create a new one. Answer yes (or press ENTER) to edit the existing configuration. The setup wizard will load all settings from the existing configuration and allow you to choose simple or manual setup. Answer no to start over with an empty configuration.

Simple setup

If you choose the simple setup, Deploy will be installed with these settings:

• The server will run with security enabled.
• The server will not use secure communication between the Deploy graphical user interface (GUI) and the Deploy server.
• The server will listen on Deploy's standard HTTP port (4516).
• The server will use / as the context root.
• The server will use a minimum of 3 and a maximum of 24 threads.
• Applications can be imported from the importablePackages directory.

Step 1 Provide a password for the admin user

The setup wizard will promote you to provide a password for the admin user. The admin user has all permissions and is used to connect to Deploy's repository.

To use the default password of admin, press ENTER twice. If you plan to connect to an existing repository, enter the password that you already use to connect to that repository.

Step 2 Initialize the repository

The setup wizard will ask if you want to initialize the repository. Answer yes to create the repository, or no to connect to an existing repository.

For information about using an external database, see Configure the Deploy SQL repository.

Step 3 Generate an encryption key

If you choose to initialize the repository, the setup wizard will ask if you want to generate an encryption key to protect passwords that you store in the repository. Answer yes if you wish to generate a new key, otherwise answer no to use the default encryption key.

• If you answer yes, an encryption key is created in XL_DEPLOY_SERVER_HOME/conf/repository-keystore.jceks. Deploy uses this key to encrypt and decrypt all password properties; it will also be used for encrypted entries in dictionaries and passwords that are set in the XL_DEPLOY_SERVER_HOME/conf/deployit.conf file.
• If you answer no, then you agree to use Deploy's own encryption key, or to use a key that you previously generated.

With the central configuration, a new security encryption policy is created for the encryption/decryption of the values in XL_DEPLOY_SERVER_HOME/conf/deployit.conf file. For more information about the password encryption policy due to the Central Configuration feature, see Encryption/Decryption Policy.

Step 4 Provide a password for the encryption key

If you choose to generate an encryption key, you can also provide a password to secure the key. You will be required to enter this password when Deploy starts, either:

• Interactively via a prompt
• Non-interactively via a command-line parameter
• Non-interactively via a configuration file

If you do not want to provide a password, press ENTER twice.

See Finish the setup process and log in to complete the setup process.

Manual setup

Manual setup gives you control over all of Deploy's installation settings.

Step 1 Provide a password for the admin user

The setup wizard will promote you to provide a password for the admin user. The admin user has all permissions and is used to connect to Deploy's repository.

To use the default password of admin, press ENTER twice. If you plan to connect to an existing repository, enter the password that you already use to connect to that repository.

Step 2 Configure secure communication

The setup wizard will prompt you to set up secure communication (SSL) between the Deploy graphical user interface (GUI) and the Deploy server.

Important: If SSL is enabled, the secure.cookie.enabled attribute is automatically set to true. As an admin, you can manually configure the secure.cookie.enabled attribute in the XL_DEPLOY_SERVER_HOME/conf/deployit.conf file.

When secure.cookie.enabled == true:

1. If you are using HTTP, you cannot log in to Deploy and the SESSION_XLD cookie is marked as secure.
2. If you are using HTTPS, you can log in to Deploy and the SESSION_XLD cookie is marked as secure.

When secure.cookie.enabled == false:

1. If you are using HTTP, you can log in to Deploy and the SESSION_XLD cookie is marked as not secure.
2. If you are using HTTPS, you can log in to Deploy and the SESSION_XLD cookie is marked as secure.

Step 3 Generate a self-signed certificate

A digital certificate is required for secure communication; normally, certificates are signed by a Certificate Authority (CA). However, if you choose secure communication between the GUI and the server, the setup wizard will ask if you want Deploy to generate a self-signed digital certificate.

Important: For security reasons, a self-signed certificate is not recommended for production environments. It may trigger security warnings in some browsers and Flash players. A self-signed certificate can only be used when you access the Deploy GUI at https://localhost:4516.

Step 4 Use your own keystore

Instead of using a self-signed digital certificate, you can use your own keystore for secure communication between the GUI and the server. Deploy's built-in Jetty server requires a certificate with the name jetty to be present in the keystore.

The setup wizard will prompt you for the keystore path (example: mykeystore.jks), the keystore type (example: jks or pkcs12), the keystore password, and the password of the jetty certificate in the keystore.

Note: The behaviour of the default keystore type (jks) depends on the JVM implementation. The Oracle implementation can detect and load both jks and pkcs12 keystore types. Other implementations, such as IBM, are less flexible and require the correct type to be configured.

Step 5 Enable mutual SSL

The setup wizard will ask if you want to enable mutual SSL which allows two parties to simultaneously authenticate each other. If you answer yes, it will prompt you for the location and password to your truststore.

For an explanation of how mutual SSL works, see this article.

Step 6 Set up the HTTP configuration

The setup wizard will ask the HTTP bind address, HTTP port number, and web context root where you would like Deploy to run.

Note: If you chose to enable secure communication, the default port will be 4517 instead of 4516.

Step 7 Set up the thread configuration

The setup wizard will prompt you for the minimum and maximum number of threads that the Deploy server should use to handle incoming connections.

Step 8 Generate an encryption key

The setup wizard will ask if you want to generate an encryption key to protect passwords that you store in the repository. Answer yes to generate a new key.

Answering yes will create an encryption key in XL_DEPLOY_SERVER_HOME/conf/repository-keystore.jceks. Deploy will use this key to encrypt and decrypt all password properties. This will also be used for encrypted entries in dictionaries and passwords that are set in the XL_DEPLOY_SERVER_HOME/conf/deployit.conf file.

If you answer no, then you agree to use Deploy's own encryption key, or to use a key that you have previously generated.

Step 9 Provide a password for the encryption key

If you choose to generate an encryption key, you can also provide a password to secure the key. You will be required to enter this password when Deploy starts, either:

• Interactively via a prompt
• Non-interactively via a command-line parameter
• Non-interactively via a configuration file

If you do not want to provide a password, press ENTER twice.

See Finish the setup process and log in to complete the setup process.

Step 10 Configure the location for importable packages

By default, you can import deployment packages from the importablePackages directory. If you would like to change this, enter a path when the setup wizard prompts you. If the directory does not exist, Deploy will create it.

Finish the setup process and log in

After you have configured all options, the setup wizard shows a summary of the configuration that you have selected. Answer yes to finish the setup process. Answer no to exit setup.

If you answer yes, the setup wizard will start Deploy and show the URL where you can access it; for example, http://localhost:4516. Open this URL in a browser and log in with the username admin and the password that you provided during the setup process. This will open the Deploy GUI.

Automatically install Deploy with default values

You can automate the installation of Deploy with a set of default values that you save in a file. This is useful, for example, when setting up Deploy using a tool such as Puppet or Ansible. To install Deploy, use the following command:

bin/run.sh -setup -reinitialize -force -setup-defaults /path/to/deployit.conf

Where the deployit.conf file contains the installation values that you want to use.

Sample of deployit.conf file

#Deploy configuration file.
#
#Notes:
# * If you modify this file, you must restart the Deploy server.
# * Use `repository.keystore.password` property to specify the password used to open the repository keystore file,
#   which contains the encryption key for the rest of the passwords.
# * The other passwords specified in this file are normally encrypted, but you can change their value using plaintext
#   and at the next start of the server the modified passwords will be re-encrypted.

admin.password=[xld_admin_password]
jcr.repository.path=repository
threads.min=3
maintenance.forbidden_paths=deployit/task\:POST,deployit/tasks/v2\:POST,deployit/control\:POST
client.server_poll.delay=30000
ssl=true
client.session.remember.enabled=true
http.bind.address=0.0.0.0
http.context.root=/
threads.max=24
ssl.mutual=false
http.upload.buffer=262144
client.session.timeout.minutes=0
http.port=4516
client.automatically.map.all.deployables=true
hide.internals=false
importable.packages.path=importablePackages
keystore.path=conf/xl-keystore.jks
keystore.keypassword=[keystore_keypassword]
keystore.password=[keystore_password]
keystore.type=jks

Configure Deploy as a daemon or service

After you successfully install the Deploy server, you can configure it to run as a daemon (Unix) or service (Windows).

Configure Deploy as a daemon on Unix

To configure Deploy to run as a daemon:

1. Ensure that the server is configured so that it can start without input from the user; for example, if a repository keystore password is required, then it should be provided in XL_DEPLOY_SERVER_HOME/conf/deployit.conf.

2. Ensure that the JAVA_HOME environment variable is set correctly for the user or daemon the will be used to run the Deploy service. You can explicitly set the location of the Java executable by updating the XL_DEPLOY_HOME/bin/.wrapper-env.sh script.

3. As root, execute XL_DEPLOY_SERVER_HOME/bin/install-service.sh. This command will install the daemon.

   You will be asked for the user name under which you installed the Deploy server when you executed run.sh.

For information about starting the Deploy daemon, refer to Start Deploy.

Configure Deploy as a service on Microsoft Windows

To configure Deploy to run as a service:

1. Ensure that the server is configured so that it can start without input from the user; for example, if a repository keystore password is required, then it should be provided in XL_DEPLOY_SERVER_HOME\conf\deployit.conf.

2. Ensure that the JAVA_HOME environment variable is set correctly for the user or service that will be used to run the Deploy service and include the location of Java/bin in the Windows Path environment variable. You can explicitly set the location of the Java executable by updating the XL_DEPLOY_HOME/bin/.wrapper-env.cmd script.

3. As an administrator, execute XL_DEPLOY_SERVER_HOME\bin\install-service.cmd. This command will install the service.

For information about starting the Deploy service, refer to Start Deploy.

Uninstall the Deploy daemon or service

To remove the installed daemon or service from the system, execute XL_DEPLOY_SERVER_HOME/bin/uninstall-service.sh (on Unix) or XL_DEPLOY_SERVER_HOME\bin\uninstall-service.cmd (on Windows).

Install Central Configuration on a Separate Server

The Central Configuration service allows you to maintain and manage shared configuration from a centralized location using Central Configuration server. For more information about Central Configuration, see Central Configuration Overview.

After you have install the Digital.ai Deploy solution, you can run the Central Configuration as a standalone service on a Docker container or Docker volume with the Docker image. To install Central Configuration service on a separate server, see Central Configuration Service as a Separate Service.

Troubleshoot the Deploy service

Deploy service does not start

If the Deploy service does not start, you can increase the startup timeout:

1. Stop the service and uninstall it.
2. In XL_DEPLOY_SERVER_HOME/conf/xld-wrapper.conf.posix (on Unix) or XL_DEPLOY_SERVER_HOME\conf\xld-wrapper.conf.win (on Windows), add the following line:

 wrapper.startup.timeout=<timeout>

Where <timeout> is the startup timeout in seconds.

1. Save the file.
2. Install the service and start it.

Deploy service occasionally fails to start or stop

On Unix-based systems, the Deploy service may occasionally fail to stop after a stop command is issued, or start after a start command is issued (as shown in the server log). If this is the case:

1. Stop the service and uninstall it.

2. In XL_DEPLOY_SERVER_HOME/conf/xld-wrapper.conf.posix, add the following line:

   wrapper.fork_hack = true

3. Save the file.

4. Install the service and start it.

Install the Deploy CLI

For information about installing the Deploy command-line interface (CLI), refer to Install the Deploy CLI.

Failover configuration

If you store the Deploy repository in a database, you can set up a failover configuration as described in Configure active/hot-standby mode.