This topic describes how to install the XL Deploy server for production.

After you install the XL Deploy server, you can optionally:

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

Verify system requirements

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

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

Extract the XL Deploy server archive

Download the XL Deploy server archive (ZIP file) from the XebiaLabs Software Distribution site (requires customer log-in).

To extract the XL 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\XL Deploy.
  3. Extract the XL Deploy server archive to the directory.
  4. Change the ownership of the installed product to xl-deploy and grant the user read access to the installation directory.
  5. 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.

Install the license

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

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

For information about the XL Deploy license, see XL Deploy licensing.

Run the server setup wizard

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

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 XL Deploy with a default configuration. This method makes it easy for you to quickly get started with XL Deploy. See Simple setup for more information.
  • Answer no to install XL Deploy manually. This method gives you explicit control over all XL Deploy settings. See Manual setup for more information.

Note: If you have installed XL 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, XL Deploy will be installed with these settings:

  • The server will run with security enabled.
  • The server will not use secure communication between the XL Deploy graphical user interface (GUI) and the XL Deploy server.
  • The server will listen on XL 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 XL 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 XL Deploy SQL repository.

Warning: If you choose to initialize the repository and you have installed XL Deploy in the same location before, any information stored in the repository will be lost.

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 to generate a new key.

Answering yes will create an encryption key in XL_DEPLOY_SERVER_HOME/conf/repository-keystore.jceks. XL Deploy will use 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 XL Deploy’s own encryption key, or to use a key that you have previously generated.

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 XL 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 XL 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 XL 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 XL Deploy graphical user interface (GUI) and the XL 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 XL Deploy and the SESSION_XLD cookie is marked as secure.
  2. If you are using HTTPS, you can log in to XL Deploy and the SESSION_XLD cookie is marked as secure. When secure.cookie.enabled == false:
  3. If you are using HTTP, you can log in to XL Deploy and the SESSION_XLD cookie is marked as not secure.
  4. If you are using HTTPS, you can log in to XL 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 XL 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 XL 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. XL 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. If you answer yes, it will prompt you for the location and password to your truststore.

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 XL 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 XL 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. XL 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 XL 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 XL 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, XL 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 XL 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 XL Deploy GUI.

XL Deploy server directory structure

After you install XL Deploy, it will have the following directory structure:

  • bin: Contains the server binaries
  • conf: Contains server configuration files and the XL Deploy license
  • doc: Contains the XL Deploy product documentation
  • ext: Contains server extensions
  • hotfix/lib: Contains hotfixes that fix issues with the server software
  • hotfix/plugins: Contains hotfixes that fix issues with the plugin software
  • importablePackages: Default location for importable deployment packages
  • lib: Contains libraries that the server needs
  • log: Contains server log files (this directory is only present once you have started XL Deploy server)
  • plugins: Contains XL Deploy middleware plugins
  • recovery.dat: Stores tasks that are in progress for recovery purposes (this file is only present after you have started XL Deploy server)
  • samples: Contains sample plugins and configuration snippets

Automatically install XL Deploy with default values

You can automate the installation of XL Deploy with a set of default values that you save in a file. This is useful, for example, when setting up XL Deploy using a tool such as Puppet or Ansible. To install XL 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

#XL Deploy configuration file.
#
#Notes:
# * If you modify this file, you must restart the XL 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 XL Deploy as a daemon or service

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

Configure XL Deploy as a daemon on Unix

To configure XL 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 XL 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 XL Deploy server when you executed run.sh.

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

Configure XL Deploy as a service on Microsoft Windows

To configure XL 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 the will be used to run the XL 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 XL Deploy service, refer to Start XL Deploy.

Uninstall the XL 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 the XL Deploy CLI

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

Failover configuration

If you store the XL Deploy repository in a database, you can set up a failover configuration as described in Configure failover for XL Deploy.