Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

systemd Services

Run xrat as a systemd user service for persistent operation and automatic startup on login.

systemd user services run under your user account (not root) and are managed with systemctl --user.

Benefits:

  • Auto-start: Service starts on login
  • Restart on failure: Automatically restarts if the process crashes
  • Logging: Integrated with journalctl

Installation

Use xrat daemon install to generate and enable the service automatically. This is the recommended approach — no manual file editing required.

xrat daemon install

To also start the daemon immediately:

xrat daemon install --start

To install the standalone HTTP API service alongside the daemon:

xrat daemon install --with-api

To preview what would be written without making changes:

xrat daemon install --dry-run

The command:

  1. Resolves the current binary path
  2. Generates xrat-daemon.service with the correct ExecStart and XRAT_PATH
  3. Writes to ~/.config/systemd/user/ (respects $XDG_CONFIG_HOME)
  4. Runs systemctl --user daemon-reload
  5. Runs systemctl --user enable xrat-daemon.service

Removal

xrat daemon uninstall

Stops, disables, and removes the service file. All user config, database, logs, and application state are preserved.

Preview first:

xrat daemon uninstall --dry-run

Management

systemctl --user start xrat-daemon
systemctl --user stop xrat-daemon
systemctl --user restart xrat-daemon
systemctl --user status xrat-daemon

View logs:

journalctl --user -u xrat-daemon -f
journalctl --user -u xrat-daemon --since today
journalctl --user -u xrat-daemon -n 100

Lingering

By default, user services stop when you log out. To keep the daemon running without an active login session (useful on servers):

loginctl enable-linger $USER

Environment Variables

The generated service file sets XRAT_PATH and RUST_LOG=info. To add secrets (API key, passwords), use an environment file.

Create ~/.config/xrat/env:

XRAT_API_KEY=your-secret-key
XRAT_POSTGRES_PASSWORD=your-db-password

Then add to the service unit after running daemon install:

[Service]
EnvironmentFile=%h/.config/xrat/env

Troubleshooting

Service won’t start:

systemctl --user status xrat-daemon
journalctl --user -u xrat-daemon -n 50

Common causes: binary not found (check ExecStart path), port already in use, config parse error (test with xrat daemon start manually).

Service stops unexpectedly:

journalctl --user -u xrat-daemon --since "1 hour ago"

Logs not appearing: ensure Environment=RUST_LOG=info is set in the unit.

Reference: Manual Setup

If you cannot use xrat daemon install (e.g., the binary is not yet in PATH), you can create the service file manually.

mkdir -p ~/.config/systemd/user

~/.config/systemd/user/xrat-daemon.service:

[Unit]
Description=XRAT Daemon
After=network.target

[Service]
Type=simple
ExecStart=/path/to/xrat daemon run-server
Restart=on-failure
RestartSec=5

Environment=XRAT_PATH=/home/user/.config/xrat
Environment=XRAT_API_KEY=
Environment=RUST_LOG=info

NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=/home/user/.config/xrat
PrivateTmp=true

[Install]
WantedBy=default.target

Replace /path/to/xrat with the actual binary location. Then:

systemctl --user daemon-reload
systemctl --user enable xrat-daemon.service
systemctl --user start xrat-daemon.service

The template files used by xrat daemon install are available in the repository at packaging/systemd/.