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.
126 lines
5.9 KiB
Markdown
126 lines
5.9 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.
|
|
|
|
* **[`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-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 <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 (`<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.
|