Server Installation

The LyftData binary is installed and available on the system. Use this guide to wire the server into systemd and choose the Linux deployment shape that matches your host.

Note

Complete the installation prerequisites and Prepare the binary before configuring the service.

Use the steps below to register the service account, install the systemd unit, and verify the control plane is reachable.

Two common Linux layouts

This guide covers two Linux patterns:

• a simple service-managed host using lyftdata-server, /etc/default/lyftdata-server, and the binary in /usr/sbin
• a reverse-proxied production host using lyftdata, /etc/lyftdata/lyftdata.env, and the binary in /opt/lyftdata/current/bin

If you already run Caddy or Nginx, prefer the reverse-proxied production pattern.

Success criteria

• The configured service reports active (running).
• Liveness responds on the URL you expect clients to use.
• The service journal contains “Server started” with no error entries.

Need a trial-only setup? Start with the Evaluation Quickstart before committing to service accounts and systemd units.

Choose a deployment pattern

Pattern	Best for	Service / env / binary	TLS model
Simple service-managed host	evaluation, small internal installs, first-time setup	lyftdata-server, /etc/default/lyftdata-server, /usr/sbin/lyftdata	LyftData serves HTTPS directly (self-signed by default)
Reverse-proxied production host	internet-facing deployments, hardened Linux hosts, rollback-friendly releases	lyftdata, /etc/lyftdata/lyftdata.env, /opt/lyftdata/current/bin/lyftdata	Caddy/Nginx terminates TLS; LyftData stays on 127.0.0.1:3000 over HTTP

Create systemd files (simple layout)

Note

Use the Linux service account template with user lyftdata and staging directory /var/lib/lyftdata-server for this simple layout. The reverse-proxied production pattern below uses lyftdata-server and /var/lib/lyftdata/lyftdata.

Create a systemd service unit file:

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

The file must contain the following:

Note

This systemd unit file assumes the binary is installed in /usr/sbin/. If the binary is installed elsewhere, adjust the ExecStart section path accordingly.

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

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

[Install]
WantedBy=multi-user.target

Create an environment file for the EnvironmentFile setting:

sudo vi /etc/default/lyftdata-server

Here, the Server is configured through either lyftdata run server options or environment variables. In this case, we’ll be using the latter.

Tip

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

At a minimum, the Server needs LYFTDATA_STAGING_DIR and LYFTDATA_LICENSE_EULA_ACCEPT. For unattended service installs, also set LYFTDATA_ADMIN_INIT_PASSWORD:

LYFTDATA_STAGING_DIR=/var/lib/lyftdata-server
LYFTDATA_LICENSE_EULA_ACCEPT=yes
LYFTDATA_ADMIN_INIT_PASSWORD=ChangeMeVerySoon

Note

If lyftdata user home directory is not LYFTDATA_STAGING_DIR, set accordingly.

We’ve added 2 additional environment variables:

• LYFTDATA_LICENSE_EULA_ACCEPT=yes prevents the one-time prompt for accepting the EULA.

• LYFTDATA_ADMIN_INIT_PASSWORD provides an initial password for the Server admin user.

If you later lose access to that account, use the operator recovery runbook: Reset an admin password.

Tip

Tune optional variables such as LYFTDATA_BIND_ADDRESS, LYFTDATA_LOG_RETENTION_DAYS, and LYFTDATA_DB_DISK_USE_MAX_PERCENT using the guidance in installation prerequisites.

If LYFTDATA_ADMIN_INIT_PASSWORD is unset, the server enters Initial Setup Required and writes a one-time setup link to /var/lib/lyftdata-server/bootstrap/initial-admin.url. journalctl shows that setup is required and where the file lives, but it does not print the token itself.

Useful local alternatives when you omit LYFTDATA_ADMIN_INIT_PASSWORD:

• sudo -u lyftdata /usr/sbin/lyftdata server bootstrap --staging-dir /var/lib/lyftdata-server --bind-address 127.0.0.1:3000 --print-url
• sudo -u lyftdata /usr/sbin/lyftdata server create-admin --staging-dir /var/lib/lyftdata-server

Note

If you plan to set LYFTDATA_BIND_ADDRESS to a non-loopback address before an admin exists, provide LYFTDATA_ADMIN_INIT_PASSWORD or complete setup while the service is still on localhost. By default the server refuses remote bootstrap on non-loopback listeners.

Note

Besides the configured data directory (LYFTDATA_STAGING_DIR), the Server will persist some minimal state information to the home directory of the user that the Server runs as (~/.local/share/lyftdata*/). This directory must be writable by the Server.

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

sudo systemctl daemon-reload

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

sudo systemctl enable lyftdata-server

Finally, start the Server:

sudo systemctl start lyftdata-server

Verify that the Server started successfully:

systemctl status lyftdata-server

It’s a good idea to inspect the startup output so you can confirm the ready splash and, if needed, see the setup URL file path:

journalctl -u lyftdata-server

The Server will be listening on LYFTDATA_BIND_ADDRESS (default 127.0.0.1:3000). HTTPS is enabled by default using a self-signed certificate.

Tip

For production, use a trusted certificate:

• Built-in TLS: provide --tls-cert and --tls-key to lyftdata run server, or
• Reverse proxy: terminate TLS in a proxy (for example Caddy or Nginx) and run the server with --disable-tls.

Certificates must include a hostname in the Subject Alternative Name (SAN) that matches the URL clients use (browser + workers).

See Networking & TLS for the recommended patterns and verification commands.

Go to https://localhost:3000/ in a browser. You will see a certificate warning because the default certificate is self-signed; proceed for evaluation. If you used LYFTDATA_ADMIN_INIT_PASSWORD, sign in as admin with that password. Otherwise, retrieve the one-time setup URL from /var/lib/lyftdata-server/bootstrap/initial-admin.url, create the admin password in the setup flow, and then sign in.

At this point, the Server is ready to start serving Workers.

Reverse-proxied production pattern

Use this pattern when the host already runs a reverse proxy, when you want the server port kept off the network, or when you want stricter systemd isolation that is closer to a production rollout.

1. Create the service account and directories

sudo useradd --system --no-create-home --shell /usr/sbin/nologin lyftdata-server
sudo install -d -m 0755 /etc/lyftdata /var/lib/lyftdata /opt/lyftdata/releases
sudo install -d -m 0750 -o lyftdata-server -g lyftdata-server /var/lib/lyftdata/lyftdata

Place the binary in a versioned release directory and point /opt/lyftdata/current at the active release:

sudo install -d -m 0755 /opt/lyftdata/releases/<release-id>/bin
sudo install -m 0755 ./lyftdata /opt/lyftdata/releases/<release-id>/bin/lyftdata
sudo ln -sfn /opt/lyftdata/releases/<release-id> /opt/lyftdata/current

This symlink pattern keeps upgrades and rollbacks predictable.

2. Create the environment file

sudoedit /etc/lyftdata/lyftdata.env

Example:

LYFTDATA_LICENSE_EULA_ACCEPT=yes
LYFTDATA_ADMIN_INIT_PASSWORD=ChangeMeVerySoon
LYFTDATA_VARIABLES_MASTER_KEY_SOURCE=env
LYFTDATA_VARIABLES_MASTER_KEY=<hex-64>
LYFTDATA_CREDENTIAL_MANAGER_MASTER_KEY_SOURCE=env
LYFTDATA_CREDENTIAL_MANAGER_MASTER_KEY=<hex-64>
RUST_LOG=info

Generate the two master keys with:

openssl rand -hex 32

Headless Linux servers should set the variable-store and credential-manager master keys explicitly in the env file. This avoids depending on an interactive desktop keyring.

Lock the env file down after editing it:

sudo chown root:root /etc/lyftdata/lyftdata.env
sudo chmod 0600 /etc/lyftdata/lyftdata.env

3. Install the hardened systemd unit

sudoedit /etc/systemd/system/lyftdata.service

Example:

[Unit]
Description=LyftData server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=lyftdata-server
Group=lyftdata-server
WorkingDirectory=/var/lib/lyftdata/lyftdata
EnvironmentFile=/etc/lyftdata/lyftdata.env
Environment=HOME=/var/lib/lyftdata/lyftdata
Environment=XDG_CONFIG_HOME=/var/lib/lyftdata/lyftdata/.config
Environment=XDG_DATA_HOME=/var/lib/lyftdata/lyftdata/.local/share
Environment=XDG_CACHE_HOME=/var/lib/lyftdata/lyftdata/.cache
ExecStart=/opt/lyftdata/current/bin/lyftdata run server --bind-address 127.0.0.1:3000 --disable-tls
Restart=on-failure
RestartSec=2
UMask=0077
NoNewPrivileges=true
PrivateTmp=true
PrivateDevices=true
ProtectSystem=strict
ProtectHome=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true
LockPersonality=true
MemoryDenyWriteExecute=true
RestrictNamespaces=true
RestrictSUIDSGID=true
RestrictRealtime=true
SystemCallArchitectures=native
RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
CapabilityBoundingSet=
SystemCallFilter=@system-service
ReadWritePaths=/var/lib/lyftdata/lyftdata

[Install]
WantedBy=multi-user.target

4. Start and verify the service

sudo systemctl daemon-reload
sudo systemctl enable --now lyftdata
sudo systemctl status lyftdata --no-pager
curl http://127.0.0.1:3000/api/liveness

If you want to inspect the sandbox posture:

systemd-analyze security lyftdata.service

5. Put a reverse proxy in front

Keep LyftData bound to 127.0.0.1:3000 and expose only the reverse proxy on 80/443.

When proxying to LyftData:

• terminate TLS in Caddy or Nginx
• forward requests to http://127.0.0.1:3000
• keep the raw 3000 listener closed to public networks
• point browsers, CLI clients, and workers at the proxy URL, not the loopback address

See Networking & TLS for the connectivity model and Security Hardening for broader host controls.

Hardening notes

• Keep CapabilityBoundingSet= empty and NoNewPrivileges=true so the service cannot gain extra privileges.
• Use ReadWritePaths=/var/lib/lyftdata/lyftdata to constrain writes to the service state directory.
• Keep /etc/lyftdata/lyftdata.env root-owned and 0600.
• Prefer /opt/lyftdata/current as a stable binary path so upgrades and rollbacks do not require unit-file edits.

When the reverse proxy is ready, open the public HTTPS URL in a browser and sign in as admin using the configured bootstrap password, or complete setup from /var/lib/lyftdata/lyftdata/bootstrap/initial-admin.url if you intentionally omitted LYFTDATA_ADMIN_INIT_PASSWORD.