131 lines
6.8 KiB
Markdown
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`.
|