docs(deploy): name the registry each agent-image path publishes to
The pinning section said CI republished ghcr.io on every push to main. CI publishes git.catlow.cloud, and only for a release tag; ghcr is where the hand-run tools/publish.sh writes, which is the reference the default names. A release zip pins a digest on a registry an anonymous pull cannot reach, and [containers].registry_auth -- the setting that fixes it -- was documented nowhere. Documented there, beside the pin. Also corrected: every shipped profile does not pin the image, and the section link omitted its number so it matched no heading.
This commit is contained in:
6 files changed
+60
-23
No files matched your search
+7
-4
@@ -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-<commit>` (immutable) instead, so a release's
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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-<commit>). See
|
||||
# deployments/systemd-user-service.md#6-pinning-the-archie-agent-image.
|
||||
image = "ghcr.io/samcharles93/archie-agent@sha256:870f1b1357979cfea23fccacb24166ebeb9ab321708ef2c2b218a763ed99b090"
|
||||
pull_policy = "missing"
|
||||
|
||||
|
||||
@@ -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-<commit>` 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-<commit>`, 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-<commit>` (`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":"<user>","password":"<token>"}`. 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
|
||||
|
||||
+1
-1
@@ -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 ─────────────────────────────────────
|
||||
|
||||
Reference in new issue
Block a user