# 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. - **[`standalone.toml`](./standalone.toml)**: start here. Event-driven automation with no forge or repositories, local Ollama models, loopback services and no tokens. - **[`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 ``` 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 server. Its two login roles are created once per database by `archie-state-store provision` -- see [Database roles](#database-roles). 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`), while a container-mode agent needs the Docker bridge gateway address, because a container cannot reach the host's loopback. A non-loopback address needs `[tls]` certificates from your own CA; see `config.example.toml`. ## Database roles The services do not connect as the database owner. `archie-state-store provision` creates, or reconciles, two login roles in an existing PostgreSQL database and hands the schema to one of them: - `archie_migrator` owns the schema and its objects and runs the goose migrations; - `archie_runtime` may read and write rows (SELECT, INSERT, UPDATE, DELETE, sequence USAGE, function EXECUTE) and has no CREATE privilege, so it cannot change the schema. Run it once per database with a role allowed to create roles and take ownership of the schema (the database owner or a superuser), then point the templates at the two roles: `database_url` is the runtime URL and `migration_database_url` the migration one. The command is idempotent, so re-running it after an upgrade reconciles objects a migration added. ```bash archie-state-store provision \ -admin-url "postgres://owner:secret@db:5432/archie" \ -runtime-url "postgres://archie_runtime:secret@db:5432/archie" \ -migration-url "postgres://archie_migrator:secret@db:5432/archie" ``` The bundled installer and `task dev` run this for you. A configuration with only `database_url` keeps working exactly as before: that one role applies the schema and serves, which is what an install that has not split the roles does. ## 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: ```bash archie-ui -config ~/.config/archie/config.toml ``` Open the dashboard to configure the organisation, workspace and first administrator account. Use HTTPS through a reverse proxy for remote access, and complete setup before exposing it publicly. `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: archie-ui authenticates to its dependencies with its `[tls]` certificate (`archie-ui.pem`). ```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 ([tls] required) archie-state-store -config ~/.config/archie/config.toml -listen 172.17.0.1:9090 ``` ## 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 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.