# Archie Core Deployment Examples This directory contains configuration templates and guides for different deployment scenarios of Archie Core. ## Directory Structure * **[`single-forge-github.toml`](./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-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`](./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`](./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`](./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`): ```bash 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: ```bash 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 ``` 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: ```bash 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. ```bash # 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 ``` ## 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: ```bash 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`: ```bash 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 (`-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.