Files
archie/deployments/README.md
T

129 lines
5.8 KiB
Markdown

# 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 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`), 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`.
## 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.