Files
archie/deployments/systemd-user-service.md
T
sam fcfe5cf264 fix(deploy): wire ExecReload so SIGHUP config reload works under systemd
archied v1.7.0 reloads its configuration on SIGHUP, but neither the unit
written by install.sh nor the one in the systemd runbook declared
ExecReload. 'systemctl --user reload archied' therefore failed, and the
only way to reach the new reload path was to know about
'systemctl --user kill -s HUP'.

The feature shipped with no supported trigger in the documented
deployment shape. Existing installs need the same line added, either by
re-running install.sh or via a drop-in.
2026-08-10 02:31:59 +10:00

2.7 KiB

Managing archied with Systemd User Services

This runbook describes how to manage archied as a background user service on Linux servers.


1. Unit File (~/.config/systemd/user/archied.service)

Create the systemd user service file at ~/.config/systemd/user/archied.service:

[Unit]
Description=Archie Core Orchestrator Daemon
After=network.target

[Service]
Type=simple
ExecStart=%h/.local/bin/archied -config %h/.config/archie/config.toml
EnvironmentFile=-%h/.config/archie/env
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=default.target

2. Enabling User Linger (loginctl)

By default, systemd terminates user services when you log out of SSH. Enabling linger allows your archied service to run continuously 24/7 across reboots and logouts:

loginctl enable-linger "$USER"

Verify linger status:

loginctl show-user "$USER" | grep Linger
# Output: Linger=yes

3. Service Commands

Reload systemd daemon files:

systemctl --user daemon-reload

Enable and start the service immediately:

systemctl --user enable --now archied

Check service status:

systemctl --user status archied

Tail live daemon logs:

journalctl --user -u archied -f

Restart or stop the service:

systemctl --user restart archied
systemctl --user stop archied

4. Running Alongside the Docker Stack

archied on the host still needs NATS and still spawns agent containers, so docker compose up -d keeps running the bus and holds the network the agents join. Two things bite in this hybrid layout:

One NATS URL serves two network namespaces. The daemon hands agent containers its own nats.url verbatim, so nats://nats:4222 (resolvable only inside compose) and nats://127.0.0.1:4222 (the container's own loopback) are both wrong. Use the compose network's gateway address, which the host and the containers can both reach:

[nats]
url = "nats://172.19.0.1:4222"

docker-compose.yml pins the subnet so that address cannot drift when the network is recreated.

pull_policy must be "missing" against a private registry. The daemon calls the Docker API with no registry credentials, so "always" gets a 401, which fails the container pool and exits the daemon. Refresh the agent image by hand instead:

docker compose pull agent

Paths. Under compose the daemon saw bind-mounted paths; on the host it sees the real ones. In particular db_path is the state-path prefix from which the daemon derives independent task and conversation SQLite files; it must point at the intended host location, or the daemon starts against empty files.