Files
archie/deployments
sam 417d379ede feat(releaseupdate): transactional self-update through archied (#1633)
archied update install verifies the release zip, checks every binary
reports the release, pulls the agent image by digest, backs up the
database in-process and stages the binaries before handing off to
archied update watchdog in its own process. The watchdog restarts units
in release order, requires archied healthy for 120s and otherwise rolls
back binaries and image policy, restoring the database only when a
migration ran. Boot recovery resumes the frozen watchdog.

Deletes scripts/archie-update-install, scripts/archie-update-watchdog,
the updater's --from-source and --auto, CommandInstaller,
ScriptInstaller and the update-image and update-topology subcommands.
2026-10-12 03:21:02 +11:00
..

Archie Core Deployment Examples

This directory contains configuration templates and guides for different deployment scenarios of Archie Core.

Directory Structure

  • single-forge-github.toml: Standard single-forge deployment managing multiple GitHub repositories under a single bot account and GitHub token.

  • multi-forge-github-gitea.toml: Multi-identity deployment running GitHub and a self-hosted Gitea instance simultaneously with distinct bot accounts, tokens, and repository sets.

  • standalone.toml: start here. Event-driven automation with no forge or repositories, local Ollama models, loopback services and no tokens.

  • docker-nats-stack.toml: Host-run archied orchestrating sandboxed archie-agent containers over the repository's Compose-managed NATS service. Copy to ~/.config/archie/config.toml, start NATS with Compose, then start archied on the host.

  • systemd-user-service.md: Operational runbook for running archied as a persistent 24/7 background service via systemd user units and loginctl enable-linger.


Usage

Copy any scenario template to your XDG configuration directory (${XDG_CONFIG_HOME:-~/.config}/archie/config.toml):

mkdir -p ~/.config/archie
cp deployments/single-forge-github.toml ~/.config/archie/config.toml

Edit API keys in ~/.config/archie/env or directly in config.toml, then launch Archie Core:

archie-gateway -config ~/.config/archie/config.toml -listen 127.0.0.1:8585 &
archie-state-store -config ~/.config/archie/config.toml -listen 127.0.0.1:9090 &
archie-messaging -config ~/.config/archie/config.toml &
archie-ui -config ~/.config/archie/config.toml &
archied -config ~/.config/archie/config.toml
# or via systemd:
systemctl --user start archied

Start order does not matter: a service waits for its peers and reports them as degraded meanwhile. Every template needs PostgreSQL 18 at database_url; docker compose up -d postgres provides the default one.

The State Store service (archie-state-store) owns the task data in the PostgreSQL database database_url names and serves the StateStore gRPC contract. BOTH archied and archie-gateway dial it via [services.state].target and never open the task tables themselves. The templates set [services.state] accordingly: a host-only agent reaches a loopback bind (127.0.0.1:9090) with no token, while a container-mode agent needs the Docker bridge gateway address plus a matching bearer token (target_token / --token / STATE_STORE_TOKEN), because a container cannot reach the host's loopback.

Running the dashboard

The dashboard is served by the standalone UI Service (archie-ui), not by archied. It reads the same config.toml, dials the Gateway and State Store targets already configured there, and binds [web].listen (127.0.0.1:8484 by default). Start it after the Gateway and the State Store:

archie-ui -config ~/.config/archie/config.toml

A non-loopback [web].listen requires a dashboard token (-token, or -token-file to mint and persist one); a loopback bind needs none. archied runs no dashboard listener at all, so webhook capture (POST /webhooks/capture/{source}) is received by archie-ui and the binding-dispatch loop in archied consumes what arrives from the shared State Store.

The dashboard speaks plain HTTP. A non-loopback bind therefore carries the session cookie and the provider token in clear over the network, and archie-ui warns about exactly that at startup. Terminate TLS in front of it (a reverse proxy or the tunnel itself) and set [web].trust_forwarded_headers = true to declare the proxy and silence the warning; leaving it off while exposing the port directly is the case the warning names.

Auth note: unlike archied, archie-ui has no secret registry -- GATEWAY_TOKEN/STATE_STORE_TOKEN resolve from its process environment only (or from [services.*].target_token in config.toml), so whatever starts archie-ui must export those tokens into its environment. See the UI Service unit in systemd-user-service.md for the worked example.

# loopback (host-only agent)
archie-state-store -config ~/.config/archie/config.toml -listen 127.0.0.1:9090
# or container-mode: bind the bridge gateway with a token
archie-state-store -config ~/.config/archie/config.toml -listen 172.17.0.1:9090 -token <token>

Verifying the daemon

archied always serves its own liveness surface on [health].listen (127.0.0.1:8485 by default). It answers 503 for the whole of boot and 200 once the daemon is running, which is what makes it a usable restart check:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8485/healthz      # 200 = daemon running, 503 = still booting
curl -s http://127.0.0.1:8485/health/detailed                               # readiness probes, 503 when degraded

The update watchdog polls this address after restarting the daemon and rolls the release back when it never answers, so a deployment that moves it must change [health].listen rather than relying on the script's fallback. The dashboard's /healthz is a separate surface on [web].listen and reports the dashboard's process, not the daemon's.

Verifying the State Store

archie-state-store exposes an optional HTTP readiness surface when launched with -ready-addr (the systemd unit uses 127.0.0.1:9091). Use it to confirm the process is up and the store is healthy before starting archied:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9091/healthz        # 200 = process up
curl -s http://127.0.0.1:9091/health/detailed                                # state_db component -> 200, or 503 when degraded

A running State Store holds the state-store ownership lock on its database; archied and archie-gateway never open the task tables directly, so a second store process on the same database_url refuses to start, and a consumer that opens the task tables indicates dual-store ownership. The readiness probe is the single-writer check the runbook has against a degraded store: a 503 from /health/detailed means archied should be started only after the store is healthy.