Every service connected to PostgreSQL as the database owner, which is a superuser, so anything that compromised an app process owned the cluster, and every connection reached the server with an empty application_name, so pg_stat_activity could not say which service a session belonged to. Split the DB credential into two login roles and name every pool: - archie_migrator owns public and its objects and runs goose. Migrations run on a short-lived pool opened from the new migration_database_url, before the serving pool opens. It is not a superuser. - archie_runtime serves requests with SELECT, INSERT, UPDATE, DELETE, sequence USAGE/SELECT and function EXECUTE only. It has no CREATE privilege, so it cannot change the schema. - Every pool sets application_name: archie-state-store, archie-gateway, and a -migrate / -recovery / -schema / -provision suffix on the transient administrative connections. Existing one-URL installs keep working: an absent migration_database_url falls back to database_url and the migration runs on the serving pool exactly as before. Provisioning is a new idempotent `archie-state-store provision` subcommand: it needs an admin URL the services never hold (database owner or superuser), creates or reconciles both roles, hands every public-schema object to the migration role, revokes PUBLIC's CREATE on public, sets row-level grants, and sets the migration role's default privileges so tables future migrations create are usable without a hand-run grant. It stores SCRAM verifiers, refuses superuser roles, and verifies the boundary before committing. install.sh now provisions the bundled path and separates the credentials: the superuser password the Compose database is created with lives only in a compose-only postgres.env, while the env file the units load holds the non-superuser PGPASSWORD. A bundled install that predates the split is upgraded in place: the roles are created, the superuser password is rotated out of the env file, and config.toml is moved to the runtime and migration URLs. External databases keep their operator-managed credential; the deployments README documents the one-shot provision command. setup writes both bundled URLs, dev:postgres provisions the dev database, the e2e stack provisions its throwaway server, and the deployment templates point at the two roles.
160 lines
7.2 KiB
Markdown
160 lines
7.2 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 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.
|