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:
4 files changed
+118
-102
No files matched your search
@@ -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, " "))
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -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
@@ -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:"
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user