# lair/containers

Container images required by lair infrastructure, built and published to the
Gitea registry at **`git.lair.cafe`**. Convention follows
[`gongfoo`](https://git.lair.cafe/gongfoo/gongfoo)'s `images/` setup.

## Layout

```
images/<name>/          one directory per image
  Containerfile         (when we author the image ourselves)
  build.sh              local build helper
  readme.md             what it is and how it's built
.gitea/workflows/
  images.yml            builds + publishes every image, on push / daily / dispatch
```

## Images

| Image | Published as | Source |
|-------|--------------|--------|
| [hermes](images/hermes/readme.md) | `git.lair.cafe/lair/hermes:{version,latest}` | built from NousResearch/hermes-agent's Dockerfile at the latest release tag |

## How builds work

- **Trigger:** push under `images/**`, a daily cron poll, or manual dispatch.
- **Release-tracking:** each image job resolves the upstream's latest release via
  its API and builds that exact ref. For upstreams that ship their own Dockerfile
  (hermes) we build directly from the upstream git context; for images we author,
  the version is passed as a `--build-arg` with the Containerfile pin as fallback.
- **Self-healing:** a build runs only when the resolved version isn't already in
  the registry — and because the registry (not a committed pin) is the source of
  truth, a failed build simply retries on the next poll instead of stranding a
  stale image. (Lesson borrowed from gongfoo.)

## Adding an image

1. `mkdir images/<name>`, add a `Containerfile` (or build from an upstream
   context) + `build.sh` + `readme.md`.
2. Add a job to `.gitea/workflows/images.yml` that logs in, builds
   `git.lair.cafe/lair/<name>:latest`, and pushes.
3. Consumers pull `git.lair.cafe/lair/<name>:latest` with `AutoUpdate=registry`.

## Required secret

| Secret | Purpose |
|--------|---------|
| `REGISTRY_TOKEN` | Gitea token with `write:package` for `git.lair.cafe`; used as `podman login -u $GITEA_ACTOR -p $REGISTRY_TOKEN`. Set in this repo's (or the `lair` org's) Actions secrets. |

Build jobs run on self-hosted runners labelled `metal` + `podman`.