The v1.30.0 extraction moved Telegram, email and webhook out of archied and into cmd/archie-messaging, and nothing packaged it. dist-zip built and copied only the five older binaries, and scripts/archie-update-install omitted it from both its service and binary lists. A host upgraded across v1.30.0 therefore ran on with no messaging process at all: archied logged that it stopped serving the telegram gateway at the extraction, nothing replaced it, and the bot was dead for two days with no error anywhere -- the daemon looked healthy throughout (archie-core-1c01). Fixed in all four places the host component set was enumerated: the zip's build loop, the zip's copy list, the installer's GATEWAY_SERVICES (messaging is a service, so it is installed AND restarted) and its GATEWAY_BINARIES. The comment claiming every process in the documented deployment ships in the zip is now true, and says what makes it true. The duplication was the actual defect, so the sets are pinned to cmd/ instead: TestHostCommandListsCannotDrift derives the host-run commands from cmd/ and asserts all four lists, plus the reference runbook's units, agree with it. Adding a command or extracting one fails the test until it is packaged -- the check that would have caught this on the day. The installer's own test grew the same coverage, and the reason it passed while the bug was live is worth recording: its fixture created only the stale cmd/ set, so the script's `[ -d ./cmd/$cmd ]` guard silently skipped messaging. Documentation, because the installer now refuses an update when a service unit is missing and sends the operator to the runbook -- so a service the runbook omits is a dead end: a messaging unit in deployments/systemd-user-service.md, the component list and start sequence in deployments/INSTRUCTIONS.md (which ships inside the zip), and the packaged-binary list in RELEASING.md. Verified: task check exit 0, including test:tools and test:ui. Both new guards were made to fail on purpose: reintroducing each omission produces "missing archie-messaging" and "no call with fragments [./cmd/archie-messaging]".
127 lines
6.0 KiB
Markdown
127 lines
6.0 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-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 <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.
|