The update watchdog verifies archied's restart, so archied has to be what answers. It was probing the dashboard's /healthz, which belongs to the dashboard: switch [web] off and nothing answers, and in the extracted UI topology that endpoint reports a different process entirely, which would confirm a release while the daemon it was meant to verify is down. [health].listen (127.0.0.1:8485, defaulted, always on) serves /healthz, /health and /health/detailed for the life of the process. Liveness answers 503 until the daemon reaches its run loop: the listener binds before the subsystems do, so an unconditional 200 would tell the watchdog a half-booted release came up. Failing to bind is fatal, because a daemon nothing can probe gets every update rolled back. The State Store's readiness surface now shares the listener plumbing, keeping its log and error text verbatim. Closes archie-core-exbz, which asked which of two bad options to take when the dashboard is off. Neither: the daemon owns its own liveness. Also deletes TestInstallUpdateDetachesInstallerFromCallbackContext. It has failed intermittently under load more than once, racing its fake bot server's multipart parse against the cancellation it induces.
4.8 KiB
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. -
local-ollama-standalone.toml: Self-hosted deployment running local LLM models via Ollama (e.g.,llama3,qwen2.5) with optional standalone (forge-disabled) operation. -
docker-nats-stack.toml: Host-runarchiedorchestrating sandboxedarchie-agentcontainers over the repository's Compose-managed NATS service. Copy to~/.config/archie/config.toml, start NATS with Compose, then startarchiedon the host. -
systemd-user-service.md: Operational runbook for runningarchiedas a persistent 24/7 background service via systemd user units andloginctl 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 &
archied -config ~/.config/archie/config.toml
# or via systemd:
systemctl --user start archied
The templates use the extracted Gateway Service by default. Start
archie-gateway before archied; it owns the conversation SQLite file and
serves the ChatContract gRPC API on the configured target.
The State Store service (archie-state-store) owns the single archie.db task
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 and never open archie.db themselves
(docs/prds/state-store-contract.md §12 step 7). 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.
# 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 owns exactly one task SQLite file (<db_path>-tasks.sqlite);
archied and archie-gateway never open archie.db directly, so a second
store process on the same db_path, or a consumer that opens the task file,
indicates dual-store ownership (docs/prds/state-store-contract.md §12 step 7/8).
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.