Worker Installation

This guide assumes you completed the installation prerequisites, staged the worker binary (lyftdata-worker), and have the Linux server configured and running.

Note

This guide assumes you are installing an external worker on its own host. Running the server and a worker on the same host is supported, but use separate service accounts and data directories per role (server vs worker) to keep permissions and state isolated.

Set up a new Worker as follows:

1. Create a Worker ID and API key on the Server.

2. Prepare the service account and data directory.

3. Create a systemd service unit file.

4. Start the Worker.

Note

Community Edition supports the built-in worker only; adding external workers requires a license. See Licensing.

Note

Use the Linux service account template with user lyftdata-worker and staging directory /var/lib/lyftdata-worker before proceeding.

Success criteria

• systemctl status lyftdata-worker reports active (running).
• The worker appears as Online in Workers (usually within ~15 seconds).
• journalctl -u lyftdata-worker | tail -n 50 shows successful registration with no authentication or connectivity errors.

Generate an API key

A Worker ID and API key are required for the Worker before it can connect to the Server. This can be done either via the web-based UI or the CLI.

Via web-based UI

Log in to the Server. Go to Workers and select Add Worker.

Create a new Worker with a specified name and ID.

The Worker name is a human-readable designation (a label), while the Worker ID will be used in the Worker configuration.

Note

A Worker ID must be unique, and may contain only ASCII letters, numbers, periods (.), and hyphens (-).

Next, create an API key for the Worker. Go to Settings → API Keys.

Then create a name for the new API key, select Add and copy the key value for later use.

Note

Key names must be between at least 5 and 50 characters in length and comprised solely of letters, numbers, dashes, and hyphens.

Create systemd files

Create a systemd service unit file:

sudo vi /etc/systemd/system/lyftdata-worker.service

Note

If you plan to run multiple workers on a host, copy the unit file with a unique name (for example lyftdata-worker1.service) and adjust the matching environment file.

The file must contain the following:

[Unit]
Description=lyftdata Worker
After=network.target auditd.service

  [Service]
  EnvironmentFile=/etc/default/lyftdata-worker
  User=lyftdata-worker
  Group=lyftdata-worker
  ExecStart=/usr/sbin/lyftdata-worker
  Restart=on-failure
  RestartSec=60

[Install]
WantedBy=multi-user.target

Create an environment file for the EnvironmentFile setting:

sudo vi /etc/default/lyftdata-worker

Here, the Worker is configured through either lyftdata-worker options or environment variables. In this case, we’ll be using the latter.

Tip

See lyftdata-worker --help for startup options and their environment variable equivalents and the reference.

At a minimum, the Worker needs to know:

• A unique Worker ID (LYFTDATA_WORKER_ID).

• An API key to authenticate against a Server (LYFTDATA_WORKER_API_KEY).

• The Server URL (LYFTDATA_URL).

• A data directory to store Job definitions and other state data (LYFTDATA_JOBS_DIR).

Therefore, the file should contain the following:

LYFTDATA_WORKER_ID=worker1
LYFTDATA_WORKER_API_KEY=<WORKER-API-KEY>
LYFTDATA_JOBS_DIR=/var/lib/lyftdata-worker
LYFTDATA_URL=https://<server>:3000
LYFTDATA_LICENSE_EULA_ACCEPT=yes
# Evaluation only: allow connecting to a self-signed TLS server certificate
LYFTDATA_TLS_INSECURE=true

Optional settings

Change the LYFTDATA_WORKER_API_KEY to match the key you previously created.

Change the LYFTDATA_URL to the Server address or hostname (confirm that your DNS is configured). Ensure the scheme matches how the server is configured (https:// by default, http:// only when the server runs with --disable-tls).

If the server is using the default self-signed certificate, keep LYFTDATA_TLS_INSECURE=true for evaluation and remove it once you install a trusted certificate.

Note

The value of LYFTDATA_WORKER_ID should match the Worker ID previously configured on the Server.

Once you have saved the service unit file, reload systemd:

sudo systemctl daemon-reload

To start the Worker at boot, enable the service with:

sudo systemctl enable lyftdata-worker

Finally, start the Worker:

sudo systemctl start lyftdata-worker

Verify that the Worker started successfully:

systemctl status lyftdata-worker

It’s a good idea to inspect the startup output, which might contain an error or warn:

journalctl -u lyftdata-worker

A Worker should now be running. It will register with the Server, using the specified API key.

The Server should indicate the Worker status on the Dashboard. At this point, the Worker is ready to run received Jobs from the Server.

Tip

If the Worker does not appear online or fails to register, see Troubleshooting for common fixes (URL, API key, ports, and logs).