diff --git a/RELEASING.md b/RELEASING.md index 6eb1e1f78..08c47ddd8 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -101,10 +101,13 @@ move nothing, which looks like success. Tagging one version produces, from a single `deploy` run: -- **Container images** — `ghcr.io/samcharles93/archied:latest` and - `ghcr.io/samcharles93/archie-agent:latest`. The runtime image is rebuilt by - the release, so runtime commits merged to `main` do not reach a running - sandbox until the host pulls the new image. +- **Container images** — `git.catlow.cloud/sam/archied:latest` and, on a + release tag, `git.catlow.cloud/sam/archie-agent:latest`. The runtime image is + rebuilt by the release, so runtime commits merged to `main` do not reach a + running sandbox until the host pulls the new image. The hand-run + `tools/publish.sh` publishes the same two images to + `ghcr.io/samcharles93` instead, which is the registry the binary's default + `[containers].image` names. - **`:latest` names the newest release, not the newest commit.** A push to `main` that is not a release publishes `archied:edge` (mutable, tracking `main`) and `archied:sha-` (immutable) instead, so a release's diff --git a/deployments/INSTRUCTIONS.md b/deployments/INSTRUCTIONS.md index a349241c2..e511966fc 100644 --- a/deployments/INSTRUCTIONS.md +++ b/deployments/INSTRUCTIONS.md @@ -21,8 +21,12 @@ of its own (`deployments/systemd-user-service.md`). `archie-agent` (the per-task sandboxed runtime) has no unit of its own: it ships beside `archied` because a Kit run mounts it from that directory. The -agent image `ghcr.io/samcharles93/archie-agent` is a separate thing, pulled by -digest for the containers `archied` spawns per task. +agent image is a separate thing, pulled for the containers `archied` spawns +per task: `[containers].image` defaults to +`ghcr.io/samcharles93/archie-agent:latest`, while this archive's `release.json` +pins the digest the release published. Set `[containers].registry_auth` when +that reference is on a registry that needs a login -- see +`deployments/systemd-user-service.md#6-pinning-the-archie-agent-image`. ## Quickstart diff --git a/deployments/docker-nats-stack.toml b/deployments/docker-nats-stack.toml index 8c28e581b..071fc515e 100644 --- a/deployments/docker-nats-stack.toml +++ b/deployments/docker-nats-stack.toml @@ -61,8 +61,8 @@ url = "nats://172.19.0.1:4222" network = "archie-core_default" # Pin your own registry's tag/digest -- never deploy against a bare # ":latest" reference, which can change under a running deployment with no -# warning. See deployments/systemd-user-service.md#pinning-the-archie-agent-image -# for the pinning convention this repo follows for its own GHCR image. +# warning. See deployments/systemd-user-service.md#6-pinning-the-archie-agent-image +# for the pinning convention this repo follows for its own agent image. image = "git.example.com/you/archie-agent:v1.21.0" # or "@sha256:..." for a production digest pin max_concurrency = 4 # Must outlast the whole-task limit (default 4h), or the reaper ends a run the diff --git a/deployments/single-forge-github.toml b/deployments/single-forge-github.toml index 04cf9af84..9bdf27649 100644 --- a/deployments/single-forge-github.toml +++ b/deployments/single-forge-github.toml @@ -53,8 +53,8 @@ mode = "embedded" [containers] # Pinned to a verified digest -- archie-agent has no published semver tag -# yet (CI only pushes :latest). See -# deployments/systemd-user-service.md#pinning-the-archie-agent-image. +# yet (a release publishes :latest and :sha-). See +# deployments/systemd-user-service.md#6-pinning-the-archie-agent-image. image = "ghcr.io/samcharles93/archie-agent@sha256:870f1b1357979cfea23fccacb24166ebeb9ab321708ef2c2b218a763ed99b090" pull_policy = "missing" diff --git a/deployments/systemd-user-service.md b/deployments/systemd-user-service.md index c9254c3bb..50300d1e4 100644 --- a/deployments/systemd-user-service.md +++ b/deployments/systemd-user-service.md @@ -134,9 +134,10 @@ Compose service or host `archie-agent` binary is required. Docker must be installed and reachable by the service user. With no explicit broker or container settings, Archie defaults `containers.image` to -`ghcr.io/samcharles93/archie-agent:latest`. Every profile shipped in -`deployments/` overrides that default with a pinned reference -- see -[Pinning the archie-agent image](#pinning-the-archie-agent-image) below. An +`ghcr.io/samcharles93/archie-agent:latest`. `single-forge-github.toml` and +`docker-nats-stack.toml` override that default with a pinned reference +(`standalone.toml` and `dev.toml` leave it) -- see +[Pinning the archie-agent image](#6-pinning-the-archie-agent-image) below. An explicit equivalent, pinned the same way, is: ```toml @@ -168,16 +169,26 @@ fall back to a host model loop. ## 6. Pinning the archie-agent Image -`ghcr.io/samcharles93/archie-agent:latest` is a moving target: every push to -`main` that touches the runtime's package closure re-publishes it -(`.github/workflows/deploy.yml`), so `latest` can change under a running -deployment with no warning and no way to reproduce a prior build. +`archie-agent:latest` is a moving target: every release re-publishes it, so it +can change under a running deployment with no warning and no way to reproduce a +prior build. Two paths publish it, to different references: -As of this writing, `archie-agent` has **no published semantic-version tag** --- CI only pushes `:latest` to GHCR (`archied` is versioned independently per -`RELEASING.md`, but that versioning is not yet reflected as a registry tag for -the agent image). Until CI publishes one, the only reproducible reference is -a content digest, resolved once and pinned explicitly: +- `.github/workflows/deploy.yml` publishes `git.catlow.cloud/sam/archie-agent` + as `:latest` and `:sha-` when the commit carries a release tag; an + ordinary push to `main` publishes nothing for the agent image. +- `tools/publish.sh`, run by hand for a release, publishes + `ghcr.io/samcharles93/archie-agent` as `:latest` and `:sha-`, which is + the registry the shipped default above names. + +A distribution zip pins whichever one its own release published, by digest, in +`release.json`; `archied update install` then pulls exactly that. + +As of this writing, `archie-agent` has **no published semantic-version tag** -- +both paths publish only `:latest` and an immutable `:sha-` (`archied` +is versioned independently per `RELEASING.md`, but that versioning is not yet +reflected as a registry tag for the agent image). Until one publishes it, the +only reproducible reference is a content digest, resolved once and pinned +explicitly: ```toml [containers] @@ -199,6 +210,25 @@ that need byte-for-byte reproducibility guarantees a tag alone cannot give (tags are mutable pointers; a compromised or accidentally-overwritten tag still resolves, a digest cannot). +A reference on a registry that needs a login needs the credential in +`[containers].registry_auth` -- the release's own +`git.catlow.cloud/sam/archie-agent` digest is one, since an anonymous pull +cannot reach it: + +```toml +[containers] +registry_auth = {engine = "env", key = "ARCHIE_REGISTRY_AUTH"} +``` + +The secret resolves to a Docker `AuthConfig` JSON document: the object +`docker login` stores under `auths`, without the surrounding map, and with a +personal access token that can read the package as the password -- +`{"username":"","password":""}`. Put it in +`~/.config/archie/env` as `ARCHIE_REGISTRY_AUTH` so it stays out of +`config.toml`. The field is file-owned and settled at boot, so a change takes +effect on restart; a value that cannot be read logs a warning and pulls +anonymously, which is the failure the task reports as a capability error. + The bundled update adapter snapshots the configured `[containers].image` before rebuilding it and restores that image if the restarted daemon fails its health check. A custom image reference is therefore supported directly in diff --git a/docker-compose.yml b/docker-compose.yml index 00981d8b1..6bbd159d4 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -94,7 +94,7 @@ services: # A tag, not the digest: Compose refuses to build an image it is told to # name by digest. The digest a task container actually runs is pinned in # the daemon's own [containers] image, so nothing here decides it. See - # deployments/systemd-user-service.md#pinning-the-archie-agent-image. + # deployments/systemd-user-service.md#6-pinning-the-archie-agent-image. image: ghcr.io/samcharles93/archie-agent:latest # ── example agent profile image ─────────────────────────────────────