Install a worker as a service

You can configure a Deploy worker to run as a daemon (Unix) or service (Windows) so that it can run as a background process without requiring user control or intervention.

Running a worker as a daemon or service applies only to local and external workers, and not to the default in-process worker. See High availability with master-worker setup for details on worker types.

Customizing worker and service

To customize a worker before starting please follow the steps mentioned below.

Create a new xl-worker.conf file in the conf folder and add the following properties for a worker.

note

Setting the values for these fields is optional, if you do not specify a value, the service will start using the default values for the properties.

• deploy.server.hostname - the hostname on which worker will be run, the default value is localhost
• deploy.server.port - port on which worker will start . The default port is 8180
• deploy.server.ssl.enabled - if set to true [Artery tls-tcp] will be used, else the default value [Artery tcp] will be used in deployit.log
• deploy.worker.name - worker name (its an optional field)

The logs for a worker running as service can be found in the wrapper.log in the log folder.

Example xl-worker.conf

The following example shows a complete xl-worker.conf for an external worker that runs as a service on its own machine and connects to the master over TLS. The comments describe what each property controls.

# XL_DEPLOY_WORKER_HOME/conf/xl-worker.conf

# Hostname or IP address that this worker advertises to the master.
# The master must be able to resolve it. Do not use localhost when the
# worker runs on a different machine than the master.
deploy.server.hostname = "xld-worker-1.example.com"

# Port on which this worker listens for the command channel from the master.
# Each worker running on the same machine must use a different port.
deploy.server.port = 8181

# Set to true to use TLS for master-worker communication.
deploy.server.ssl.enabled = false

# Name shown for this worker under Monitoring in the Explorer. Assign a unique name to each worker for easier identification. This is an optional field.
deploy.worker.name = "worker-1"

Restart the worker service after you change xl-worker.conf.

Configure multiple workers as services

important

If you want to configure multiple workers as services, they need to be started as external workers with a separate folder for each worker.

See External worker setup for more information on setting up multiple workers as service.

For configuring multiple workers, you must also update the following attributes in the xld-wrapper-worker.conf under the conf folder with a unique worker service name.

wrapper.console.title=Deploy Worker
wrapper.ntservice.name=xl-deploy-worker
wrapper.ntservice.displayname=Deploy Worker

For example:

wrapper.console.title=Deploy Worker-2
wrapper.ntservice.name=xl-deploy-worker-2
wrapper.ntservice.displayname=Deploy Worker-2

Each worker needs its own installation folder, its own xl-worker.conf, and its own service name. The following table shows the values for two workers installed on the same machine.

Setting	File	Worker 1	Worker 2
Installation folder	Not applicable	/opt/xebialabs/xld-worker-1	/opt/xebialabs/xld-worker-2
deploy.server.port	conf/xl-worker.conf	8181	8182
deploy.worker.name	conf/xl-worker.conf	worker-1	worker-2
wrapper.ntservice.name	conf/xld-wrapper-worker.conf	xl-deploy-worker-1	xl-deploy-worker-2
wrapper.ntservice.displayname	conf/xld-wrapper-worker.conf	Deploy Worker-1	Deploy Worker-2
wrapper.console.title	conf/xld-wrapper-worker.conf	Deploy Worker-1	Deploy Worker-2

Run install-service.sh worker or install-service.cmd worker from each installation folder after you set these values.

Configure Deploy as a daemon on Unix

To install a Deploy worker to run as a daemon:

1. Ensure that the worker 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/centralConfiguration/deploy-server.yaml.
2. Ensure that the JAVA_HOME environment variable is set correctly for the user or daemon that will be used to run the Deploy service. You can explicitly set the location of the Java executable by updating the XL_DEPLOY_WORKER_HOME/bin/.wrapper-env.sh script.
3. As root, execute XL_DEPLOY_WORKER_HOME/bin/install-service.sh worker.
4. You are prompted for:
   • Connection details for the Deploy master (HOST:PORT)
   • The URL for the Deploy REST API

This command will install and start the daemon.

Example: The service command below provides an example of running workers as a service with multiple master switches on Unix:

./install-service.sh worker -api http://loadbalancer:8080 -master http://master_url1:8180 -master http://master_url2:8180 -master http://master_url3:8180

See High availability with master-worker setup for understanding how -api and -master switches work.

Configure Deploy as a service on Microsoft Windows

To configure Deploy worker to run as a service:

1. Ensure that the worker 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\CentralConfiguration\deploy-server.yaml.
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.

To set the location of the Java executable, run the following command:

XL_DEPLOY_WORKER_HOME/bin/.wrapper-env.cmd.

3. As an administrator, run the following command:

XL_DEPLOY_WORKER_HOME\bin\install-service.cmd worker.

You will be prompted to enter the following details:

• Connection details for the Deploy master (HOST:PORT)
• The URL for the Deploy REST API

This command will install and start the service.

Example: The service command below provides an example of running workers as a service with multiple master switches on Windows:

./install-service.cmd -api http://loadbalancer:8080 -master http://master_url1:8180 -master http://master_url2:8180 -master http://master_url3:8180

See running workers with multiple masters switches for understanding how -api and -master switches work.

Best practices for multi-worker setups

These practices apply when you run more than one worker as a service against the same master or set of masters.

Master-worker communication

Follow these guidelines to keep the master and its workers connected:

• Assign a unique deploy.server.port to every worker that runs on the same machine, and a unique deploy.worker.name to every worker in the setup. Duplicate ports prevent the second service from starting, and duplicate names make workers hard to tell apart in the Workers list.
• Set deploy.server.hostname to an address the master can resolve. The master and all registered workers must reside in the same sub-network.
• Keep every worker on the same configuration as the master. The folder structure, contents, and plugins must be identical, and all instances must use the same database. The master does not assign new tasks to a worker whose configuration differs.
• Configure the JMS broker and the task queues identically on the master and on every worker. See Configure Task Queuing.
• In an active/hot-standby or active/active setup, point -api at the load balancer endpoint and -master at the DNS service name for Deploy, not at an individual master.
• Enable TLS on the command channel with deploy.server.ssl.enabled on both the master and the workers. See Configure secure communication with workers and satellites.

Encrypted password handling

A worker that runs as a service starts without user input, so every password it requires must be available in configuration before the service starts:

• Provide the repository keystore password before you install the service. Set it in XL_DEPLOY_SERVER_HOME/centralConfiguration/deploy-server.yaml, or set the repository.keystore.password key in deployit.conf. A service that waits for the password at the prompt stops immediately after it starts.
• Copy conf/repository-keystore.jceks from the master to each worker. The worker uses the encryption key in this file to decrypt passwords stored in the repository. Without the same key, tasks that use encrypted CI properties or dictionary entries fail on the worker.
• Copy the xl.spring.cloud.encrypted.key value from the master deployit.conf to each worker so that {cipher} values in the central configuration files resolve on the worker.
• Do not leave plaintext passwords in configuration files. Deploy encrypts the passwords in deployit.conf when it starts for the first time, and stores central configuration secrets as {cipher} values.
• Restrict file permissions on conf/deployit.conf, conf/repository-keystore.jceks, and the key store and trust store files to the account that runs the worker service.

For more information about password encryption, see Manage system passwords and Store encrypted passwords in Deploy.

Uninstall the Deploy daemon or service

To remove the installed daemon or service from the system, run the appropriate command:

Operating system	Command
Microsoft Windows	XL_DEPLOY_WORKER_HOME\bin\uninstall-service.cmd
Unix-based systems	XL_DEPLOY_WORKER_HOME/bin/uninstall-service.sh

Troubleshooting

This section covers the problems that occur most often when you run one or more workers as a service. Check wrapper.log in the log folder of the worker for service startup errors, and deployit.log for worker runtime errors.

Worker fails to connect to the Master

The Worker fails to connect to the Master when deploy.server.ssl.enabled is set to true. To resolve this issue, configure the following command line argument for a worker startup:

 -keyPassword KEY_PASSWORD                : Password for the key (default: changeme)
 -keyStore KEY_STORE_PATH                 : Path to the key store  (default: keystore)
 -keyStorePassword KEY_STORE_PASSWORD     : Password for the key store (default: changeme)
 -trustStore TRUST_STORE_PATH             : Path to a trust store (default: truststore)
 -trustStorePassword TRUST_STORE_PASSWORD : Password for a trust store (default: changeme)

Worker service starts but the worker does not register with the master

The service runs, but the worker does not appear in the Workers list under Monitoring in the Explorer. Check the following:

• The -master value points to the host and remoting port that the master reports at startup. The master logs the line External workers can connect to xld-master-host:8180 when it starts.
• The -api value points to the REST endpoint of the master, or to the load balancer endpoint in an active/hot-standby or active/active setup.
• The deploy.server.hostname value in xl-worker.conf resolves from the master. A worker on a remote machine that advertises localhost registers an address the master cannot reach.
• The master and the worker are in the same sub-network, and the remoting port is open in both directions.

Worker service fails to start because the port is in use

A second worker on the same machine fails to start when it uses the port of an existing worker or of the master. The default worker port is 8180. Set a distinct deploy.server.port in the xl-worker.conf of each worker, then restart the service.

Installing a second worker service overwrites the first one

Windows registers services by name. When two installation folders keep the default wrapper.ntservice.name, the second install-service.cmd worker run replaces the first service instead of adding one. Set a unique wrapper.ntservice.name, wrapper.ntservice.displayname, and wrapper.console.title in the xld-wrapper-worker.conf of each worker before you install the service.

Worker is shown as Incompatible or moves to Draining state

The master marks a worker as Incompatible when the worker runs a different configuration, plugin set, or type system than the master, and it stops assigning new tasks to that worker. Synchronize the configuration folder and plugins of the worker with the master, then restart the worker service. See Changing configuration of masters and workers.

Worker fails to start with an HTTP 401 from central configuration

The worker cannot read the central configuration and the log records a 401 response. This occurs when the credentials that the worker uses do not match the master or the standalone central configuration service. Verify that:

• admin.username and admin.password in the worker deployit.conf match the credentials on the master.
• xl.spring.cloud.uri points to the master, the load balancer, or the standalone central configuration service, and xl.spring.cloud.external-config is set correctly for your setup. See Central Configuration for Deploy workers.

Worker starts but encrypted passwords fail to resolve

Tasks fail on the worker with decryption errors, while the same tasks succeed on the master. The worker does not hold the encryption key that the values were encrypted with. Copy conf/repository-keystore.jceks and the xl.spring.cloud.encrypted.key value from the master to the worker, then restart the worker service.

Worker service stops immediately after it starts

The worker prompts for the repository keystore password and the service has no console to answer it. Provide the password in deploy-server.yaml or set repository.keystore.password in deployit.conf, then restart the service.