diff --git a/deploy_workflow_test.go b/deploy_workflow_test.go index 0be9b8a95..4bb9fabd0 100644 --- a/deploy_workflow_test.go +++ b/deploy_workflow_test.go @@ -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, " ")) } } diff --git a/deployments/systemd-user-service.md b/deployments/systemd-user-service.md index 6b198240e..96832982d 100644 --- a/deployments/systemd-user-service.md +++ b/deployments/systemd-user-service.md @@ -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 ` 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. --- diff --git a/install.sh b/install.sh index ae10c61af..54f82e4e7 100755 --- a/install.sh +++ b/install.sh @@ -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 < "${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 < "${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 < "${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 < "${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 < "${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 < "${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:" diff --git a/scripts/archie-update-install b/scripts/archie-update-install index c1fa695b3..e4130056a 100755 --- a/scripts/archie-update-install +++ b/scripts/archie-update-install @@ -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