feat(install): write a unit for every host service

install.sh built and installed five host binaries but wrote only
archied.service, so a fresh install ran one of five services and the updater
refused its own first update for units the installer never created
(archie-core-enow). The runbook stood in as the mechanism, which is the
hand-written step that let a messaging binary and unit drift apart
(archie-core-1c01).

- install.sh writes archie-state-store.service, archie-gateway.service,
  archie-ui.service and archie-messaging.service alongside archied.service,
  with the contents the runbook used to tell an operator to paste, and starts
  all five with the store first.
- deployments/systemd-user-service.md no longer carries the unit contents; it
  names the units, explains why each exists, and points at
  systemctl --user cat and drop-ins for inspection and overrides.
- The updater's unmanaged-unit refusal now reads as a safety net for a host
  that drifted rather than the normal path.
This commit is contained in:
sam committed 2026-09-22 14:41:38 +10:00
1 parent 323870a9f6
commit 3d6accd7e9
4 files changed
+118 -102

No files matched your search

+5 -2
View File
@@ -152,15 +152,18 @@ func TestDistZipShipsEveryHostCommand(t *testing.T) {
// The installer now REFUSES an update when a service unit is missing and
// tells the operator to create it from this runbook, so a service the
// runbook never shows is a dead end rather than a documentation gap.
// The installer writes the units, so the runbook no longer carries their
// contents; it must still name each unit, or an operator cannot find one to
// inspect or override.
runbook := readDeploymentFile(t, filepath.Join("deployments", "systemd-user-service.md"))
var undocumented []string
for _, service := range wantServices {
if !strings.Contains(runbook, "/bin/"+service+" ") {
if !strings.Contains(runbook, service+".service") {
undocumented = append(undocumented, service)
}
}
if len(undocumented) > 0 {
t.Errorf("deployments/systemd-user-service.md documents no unit for: %s", strings.Join(undocumented, " "))
t.Errorf("deployments/systemd-user-service.md names no unit for: %s", strings.Join(undocumented, " "))
}
}
+22 -89
View File
@@ -4,46 +4,19 @@ This runbook describes how to manage `archied` as a background user service on L
---
## 1. Unit Files (`~/.config/systemd/user/archied.service` and `archie-gateway.service`)
## 1. Unit Files (written by `install.sh`)
Create the systemd user service file at `~/.config/systemd/user/archied.service`:
`install.sh` writes all five units -- `archied.service`, `archie-state-store.service`,
`archie-gateway.service`, `archie-ui.service` and `archie-messaging.service` --
with the contents it
ships. This page describes what runs and why; the installer owns the contents,
so inspect a unit with `systemctl --user cat <unit>` rather than copying it from
here, where it would drift from what is written.
```ini
[Unit]
Description=Archie Core Orchestrator Daemon
After=network.target
The Gateway unit is `archie-gateway.service`, written by `install.sh` beside
`archied.service`.
[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
```
Create the Gateway Service unit beside it:
```ini
[Unit]
Description=Archie Gateway Service
After=network.target
[Service]
Type=simple
ExecStart=%h/.local/bin/archie-gateway -config %h/.config/archie/config.toml -listen 127.0.0.1:8585
EnvironmentFile=-%h/.config/archie/env
Restart=on-failure
RestartSec=5s
[Install]
WantedBy=default.target
```
Create the State Store unit beside it. It owns the single `archie.db` SQLite
The State Store unit is `archie-state-store.service`. It owns the single `archie.db` SQLite
file and serves the `StateStore` gRPC contract. After the in-process store path
was deleted, BOTH `archied` and `archie-gateway` dial it via
`[services.state].target` (see the `archied` config below) and never open
@@ -53,21 +26,7 @@ agent needs the Docker bridge gateway address plus a bearer token via
`--token`/`STATE_STORE_TOKEN` or `[services.state].target_token`, and a
non-loopback bind fails closed without one:
```ini
[Unit]
Description=Archie State Store Service
After=network.target
[Service]
Type=simple
ExecStart=%h/.local/bin/archie-state-store -config %h/.config/archie/config.toml -listen 127.0.0.1:9090 -ready-addr 127.0.0.1:9091
EnvironmentFile=-%h/.config/archie/env
Restart=on-failure
RestartSec=5s
[Install]
WantedBy=default.target
```
`install.sh` writes `archie-state-store.service` with that loopback bind.
---
@@ -78,30 +37,18 @@ by `archied`, since the v1.30.0 extraction. `archied` starts no gateway for them
and logs nothing when one is absent, so a host that updates across v1.30.0
without this unit runs on with dead channels and a daemon that looks perfectly
healthy -- that was `archie-core-1c01`, found after two days of a silently dead
Telegram bot. `scripts/archie-update-install` refuses an update when a service
unit is missing and names what is missing, so create this one before updating.
Telegram bot. `install.sh` writes this unit on a fresh install;
`scripts/archie-update-install` refuses an
update when a host is missing a unit and names what is missing, which now fires
for a host that drifted or predates this release rather than the normal path.
It dials the Gateway for the chat contract and the State Store for the stored
channel settings, and reads the same `config.toml`. Like `archie-ui` it resolves
`GATEWAY_TOKEN` and `STATE_STORE_TOKEN` from its process environment, hence the
`EnvironmentFile`:
```ini
[Unit]
Description=Archie Messaging Service
After=network.target archie-gateway.service archie-state-store.service
Wants=archie-gateway.service archie-state-store.service
[Service]
Type=simple
ExecStart=%h/.local/bin/archie-messaging -config %h/.config/archie/config.toml
EnvironmentFile=-%h/.config/archie/env
Restart=on-failure
RestartSec=5s
[Install]
WantedBy=default.target
```
`install.sh` writes `archie-messaging.service`, whose `After=` and `Wants=`
lines preserve that store-then-gateway order.
## 2. UI Service Unit (`~/.config/systemd/user/archie-ui.service`)
@@ -126,22 +73,8 @@ probe (token-free by design); the authenticated readiness surface lives at
the dashboard's health endpoint behind the token. A watchdog can curl
`/healthz` without credentials.
```ini
[Unit]
Description=Archie UI Service
After=network.target archie-state-store.service
Wants=archie-state-store.service
[Service]
Type=simple
ExecStart=%h/.local/bin/archie-ui -config %h/.config/archie/config.toml
EnvironmentFile=-%h/.config/archie/env
Restart=on-failure
RestartSec=5s
[Install]
WantedBy=default.target
```
`install.sh` writes `archie-ui.service`. It has no secret registry of its own,
so its token handling is the `EnvironmentFile` note above.
Concretely, for a deployment whose dependency tokens live outside
`config.toml`, `~/.config/archie/env` carries the two names and the unit
@@ -159,9 +92,9 @@ process closes that gap itself: its event pump retries priming with backoff
until the State Store answers, so the activity feed goes live once the store
is up rather than staying history-only until the next restart.
```ini
ExecStart=%h/.local/bin/archie-ui -config %h/.config/archie/config.toml -token-file %h/.local/share/archie/web-token
```
For a non-loopback bind, override the installed unit's `ExecStart` with
`-token-file %h/.local/share/archie/web-token` (or `-token`) in a drop-in rather
than editing the installer's copy in place.
---
+90 -10
View File
@@ -415,11 +415,15 @@ fi
SERVICE_INSTALLED=false
if [ "${INSTALL_SYSTEMD}" = true ] && command -v systemctl &>/dev/null && [ -d "${XDG_CONFIG_HOME}" ]; then
SYSTEMD_USER_DIR="${XDG_CONFIG_HOME}/systemd/user"
SERVICE_FILE="${SYSTEMD_USER_DIR}/archied.service"
echo "==> Configuring systemd user service..."
echo "==> Configuring systemd user services..."
mkdir -p "${SYSTEMD_USER_DIR}"
cat <<EOF > "${SERVICE_FILE}"
# Every service this installer builds gets a unit, with the contents the
# runbook used to tell an operator to paste by hand. The runbook is a
# description now, not the mechanism: a fresh install must not need four
# hand-written units before its own updater will run (archie-core-enow), and
# the contents must not live in two places to drift apart.
cat <<EOF > "${SYSTEMD_USER_DIR}/archied.service"
[Unit]
Description=Archie Core Orchestrator Daemon
After=network.target
@@ -443,9 +447,82 @@ RestartSec=5s
[Install]
WantedBy=default.target
EOF
# The State Store owns archie.db and is the process everything else dials, so
# its unit is the first dependency the others name.
cat <<EOF > "${SYSTEMD_USER_DIR}/archie-state-store.service"
[Unit]
Description=Archie State Store Service
After=network.target
[Service]
Type=simple
ExecStart=${ARCHIE_BIN_DIR}/archie-state-store -config ${ARCHIE_CONFIG_DIR}/config.toml -listen 127.0.0.1:9090 -ready-addr 127.0.0.1:9091
EnvironmentFile=-${ENV_FILE}
Restart=on-failure
RestartSec=5s
[Install]
WantedBy=default.target
EOF
cat <<EOF > "${SYSTEMD_USER_DIR}/archie-gateway.service"
[Unit]
Description=Archie Gateway Service
After=network.target
[Service]
Type=simple
ExecStart=${ARCHIE_BIN_DIR}/archie-gateway -config ${ARCHIE_CONFIG_DIR}/config.toml -listen 127.0.0.1:8585
EnvironmentFile=-${ENV_FILE}
Restart=on-failure
RestartSec=5s
[Install]
WantedBy=default.target
EOF
cat <<EOF > "${SYSTEMD_USER_DIR}/archie-ui.service"
[Unit]
Description=Archie UI Service
After=network.target archie-state-store.service
Wants=archie-state-store.service
[Service]
Type=simple
ExecStart=${ARCHIE_BIN_DIR}/archie-ui -config ${ARCHIE_CONFIG_DIR}/config.toml
EnvironmentFile=-${ENV_FILE}
Restart=on-failure
RestartSec=5s
[Install]
WantedBy=default.target
EOF
# The Telegram, email and webhook channels run here, not in archied: without
# this unit a host looks healthy while its channels are dead (archie-core-1c01).
cat <<EOF > "${SYSTEMD_USER_DIR}/archie-messaging.service"
[Unit]
Description=Archie Messaging Service
After=network.target archie-gateway.service archie-state-store.service
Wants=archie-gateway.service archie-state-store.service
[Service]
Type=simple
ExecStart=${ARCHIE_BIN_DIR}/archie-messaging -config ${ARCHIE_CONFIG_DIR}/config.toml
EnvironmentFile=-${ENV_FILE}
Restart=on-failure
RestartSec=5s
[Install]
WantedBy=default.target
EOF
systemctl --user daemon-reload || true
SERVICE_INSTALLED=true
echo " Installed ${SERVICE_FILE}"
for unit in archied archie-state-store archie-gateway archie-ui archie-messaging; do
echo " Installed ${SYSTEMD_USER_DIR}/${unit}.service"
done
# Enable linger so systemd --user runs continuously without an active login
# session. $(id -un) is used rather than $USER, which is unset in some
@@ -465,10 +542,12 @@ EOF
fi
fi
# Auto-enable and start service
# Auto-enable and start the services, the store first so a fresh boot does
# not race a dial it depends on.
if [ "${AUTO_START}" = true ]; then
echo "==> Enabling and starting archied systemd service..."
systemctl --user enable --now archied || echo " Notice: Could not start service automatically. Check systemctl --user status archied"
echo "==> Enabling and starting Archie services..."
systemctl --user enable --now archie-state-store archie-gateway archied archie-ui archie-messaging ||
echo " Notice: Could not start every service automatically. Check: systemctl --user status archied archie-state-store archie-gateway archie-ui archie-messaging"
fi
fi
@@ -479,7 +558,7 @@ echo " ✓ Archie Core Installation Complete!"
echo "============================================================"
echo ""
echo "Installation Details:"
echo " - Binaries : ${ARCHIE_BIN_DIR}/archied"
echo " - Binaries : ${ARCHIE_BIN_DIR}/{archied,archie-state-store,archie-gateway,archie-ui,archie-messaging,archie-playbooks}"
echo " - Agent image: ghcr.io/samcharles93/archie-agent:latest"
echo " - Config : ${ARCHIE_CONFIG_DIR}/config.toml"
echo " - Secrets : ${ENV_FILE}"
@@ -523,8 +602,9 @@ fi
if [ "${SERVICE_INSTALLED}" = true ] && [ "${AUTO_START}" = true ]; then
echo "Service Management:"
echo " - Units installed : archied archie-state-store archie-gateway archie-ui archie-messaging"
echo " - View live logs : journalctl --user -u archied -f"
echo " - Service status : systemctl --user status archied"
echo " - Service status : systemctl --user status archied archie-state-store archie-gateway archie-ui archie-messaging"
echo " - Restart daemon : systemctl --user restart archied"
else
echo "Manual Startup:"
+1 -1
View File
@@ -203,7 +203,7 @@ if [[ ",$components," == *,daemon,* ]]; then
done
if [ -n "$unmanaged_units" ]; then
echo "refusing to install archied $GW: this host runs units the update does not manage: $unmanaged_units" >&2
echo "the installed $BIN_DIR/archie-update-install predates them; install scripts/archie-update-install from archied/v$GW, then retry" >&2
echo "a current install.sh writes units for: $GATEWAY_SERVICES. If the installed updater predates this release, replace $BIN_DIR/archie-update-install with scripts/archie-update-install from archied/v$GW; otherwise remove the extra unit, or add it to GATEWAY_SERVICES if this host is meant to run it." >&2
exit 1
fi
fi