Files
archie/deployments/INSTRUCTIONS.md
T

131 lines
6.8 KiB
Markdown

# Running this distribution
This archive contains five linux/amd64 binaries:
Each service owns its data and reaches the others only through their gRPC
contracts (or NATS, for task actions):
| Service | Owns | Reaches |
|---|---|---|
| `archie-state-store` | tasks, events, control-plane settings, identities and access policies, installed packages (PostgreSQL) | nothing |
| `archie-gateway` | conversations (PostgreSQL, its own tables) and every model call: chat turns, curators, MCP tools and sampling | State Store; daemon over NATS for task actions |
| `archied` | dispatch: forge polling, the task queue, the embedded NATS broker, agent containers | State Store; Gateway |
| `archie-messaging` | the Telegram, email and webhook channel connections | Gateway; State Store for channel settings |
| `archie-ui` | the dashboard and the webhook capture receiver | Gateway; State Store |
`archied playbooks lint` checks playbook binding YAML before it reaches the
daemon, and `archied playbooks serve` is its language server for editors.
Without `archie-messaging` the channels are simply absent, so it needs a unit
of its own (`deployments/systemd-user-service.md`).
`archie-agent` (the per-task sandboxed runtime) is **not** in this archive —
it only ever runs inside the Docker container `archied` spawns per task, never
as a host binary. Pull it from GHCR: `ghcr.io/samcharles93/archie-agent`.
## Quickstart
1. Pick a starting configuration. The full set of annotated templates lives
in this repository's `deployments/` directory on GitHub
(<https://github.com/samcharles93/archie-core/tree/main/deployments>) —
`standalone.toml` (no forge, the simplest start),
`single-forge-github.toml` and `docker-nats-stack.toml` cover the common cases. Every one needs
PostgreSQL 18 at `database_url`. Copy whichever fits to:
```bash
mkdir -p ~/.config/archie
cp <template>.toml ~/.config/archie/config.toml
```
2. Edit `config.toml` (forge token, repos, `[services.state]` target, model
providers) and place any secrets in `~/.config/archie/env` or referenced
`secret://` locations.
3. Start the five processes. Order does not matter: a service whose peer is
not up yet waits for it and reports it as degraded on its health surface
meanwhile. The Gateway waits for the daemon's NATS endpoint when the broker
is embedded.
```bash
./archie-state-store -config ~/.config/archie/config.toml -listen 127.0.0.1:9090 &
./archie-gateway -config ~/.config/archie/config.toml -listen 127.0.0.1:8585 &
./archie-messaging -config ~/.config/archie/config.toml &
./archie-ui -config ~/.config/archie/config.toml &
./archied -config ~/.config/archie/config.toml
```
Open `[web].listen` (default `127.0.0.1:8484`) to configure the organisation,
workspace and first administrator account. Remote access requires an HTTPS
reverse proxy. Complete setup before exposing the dashboard publicly.
4. For a persistent, 24/7 deployment instead of a foreground run, follow the
systemd user-unit runbook:
<https://github.com/samcharles93/archie-core/blob/main/deployments/systemd-user-service.md>.
## Verifying an install
`archied playbooks lint -dir <playbooks-dir>` validates playbook binding YAML
against the same schema `archied` loads at startup — run it against your
playbooks directory before pointing `archied` at it.
## Version
This archive's binaries are built from the `archied` release tag in its
filename; `archie-ui`, `archie-gateway`, `archie-state-store` and
`archie-messaging` ship at that same version rather than
being independently tagged (see `RELEASING.md` in the source repository for why
only `archied` and `archie-agent` are independently versioned).
`archie-state-store`, `archie-gateway`, `archie-messaging`, `archie-ui` and
`archied` are services that must be running and addressable; `archie-messaging`
carries the Telegram, email and webhook channels since the v1.30.0 extraction, so
an install (or an upgrade across v1.30.0) needs its unit as well -- see
`deployments/systemd-user-service.md`.
### Native self-update
Install on Settings → Status runs `archied update install -version X`, which
downloads the release's Linux/amd64 zip and verifies it against `SHA256SUMS`
before unpacking it. Every host binary in the zip must report `X`. It then pulls
the agent image `release.json` pins by digest, backs up the database to
`db.pre-update.dump` in the state directory, stages the new binaries beside the
live ones and hands the transaction to `archied update watchdog` in a process of
its own (a transient systemd user unit). Nothing that runs changes until the
watchdog takes over.
`archied update check` finds the newest GitHub release with a linux-amd64 zip on
the channel chosen under Settings → Status → Updates: stable, next (includes
prereleases) or a pinned version. From a shell it reads
`ARCHIE_UPDATE_RELEASE_CHANNEL` and `ARCHIE_UPDATE_PIN`, or `-channel` and `-pin`.
The notification destination remains separate from the release channel.
`release.json` supplies the service order and required config sections to both
first-install and self-update. A missing unit or config section produces an
ordered migration plan and refuses installation. Apply that plan before retrying.
Automatic topology edits are intentionally unsupported.
The watchdog stops the units in reverse `release.json` order, switches the
staged executables by rename, switches the control-plane image policy (only the
image field, with conflict detection), and restarts the units in order through
`systemctl --user`. archied must report the new version and stay healthy for
120 seconds. Otherwise the watchdog restores the previous binaries and image
policy. Data is not rolled back unless the new release migrated the database:
then the previous binaries cannot serve it, so the pre-update backup is restored
and the outcome report says that every write since the update began is gone.
Without a systemd user manager the watchdog switches binaries and image policy
but restarts nothing, and the install reports that the services need a manual
restart.
Transactions live in `${XDG_STATE_HOME:-~/.local/state}/archie/update`, outside
the binary directory: `transaction/journal.json`, `transaction/previous/`, and
`transaction/archied`, the frozen copy of the archied that wrote the journal. On
daemon boot, an interrupted transaction is
handed to that frozen watchdog with `-recover` before normal startup: a
transaction that never started is discarded, one that was switching or observing
is rolled back, and a decided one is finished. To recover manually, run
`transaction/archied update watchdog -recover -bin-dir ~/.local/bin` from that
state directory. A failed recovery keeps the journal for another attempt.
The database backup stays in the state directory after a committed update for
manual recovery with `archie-state-store restore`.