Bead archie-core-8cda.5.5: - task dev now runs archie-ui (dev:dashboard) on :8484 -- after the cutover archied binds no dashboard listener, and Vite's /api,/events proxy needs a live receiver there. dev:mobile starts archie-ui with a LAN bind and -token-file (reusing the pre-cutover token path) instead of a mobile archied overlay; dev:ui's summary points at archie-ui. - deployments/dev.toml documents itself as the archie-ui overlay and states the [services.gateway] target explicitly. - systemd-user-service.md: the auth gap is now the documented posture -- archie-ui has no secret registry, resolves GATEWAY_TOKEN/ STATE_STORE_TOKEN from its process environment only, so the starter (EnvironmentFile) exports them; worked env-file example added, plus /healthz as the token-free liveness probe. - INSTRUCTIONS.md ships five binaries with archie-ui in the quickstart and the token story; README.md carries the auth note; the docker-nats-stack profile notes archie-ui binds [web] and dials the same [services.*] targets. - release tooling: archied's component closure extends with cmd/archie-ui and internal/app/archieui, so a UI-process-only commit can no longer fall between the two changelogs; RELEASING.md documents that the UI Service ships inside the archied release.
5.9 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 &
archie-ui -config ~/.config/archie/config.toml &
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.
Running the dashboard
The dashboard is served by the standalone UI Service (archie-ui), not by
archied (UI cutover, archie-core-8cda.5.4; docs/prds/ui-service-boundary.md).
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.
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 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.