# images

Custom container images, published to the public
[`rmcguire`](https://gitea.libretechconsulting.com/rmcguire/-/packages) registry
on Gitea.

Each image is self-contained in its own directory under `images/`: a `Dockerfile`,
a `README.md`, and an optional `test.sh`.

## Images

| Image | Base | Purpose |
| --- | --- | --- |
| [`node-agent`](images/node-agent) | `node:22-alpine` | Node 22 plus a GNU shell, network and Kubernetes toolchain — a general-purpose command execution environment for AI agents |

## Pulling

```sh
docker pull gitea.libretechconsulting.com/rmcguire/node-agent:latest
```

The registry is public, so no pull secret is required.

## Tags

| Tag | Points at | Set by |
| --- | --- | --- |
| `latest` | the current tip of `main` | push to `main` |
| `main-<sha>` | one specific commit on `main` | push to `main` |
| `vX.Y.Z` / `vX.Y` / `vX` | an immutable released build | tag `<image>/vX.Y.Z` |
| `pr-<n>` | a pull request build — built, never published | pull request |

`latest` has exactly one owner — `main` — so a release tag and a `main` build can
never race to define it. Pin to `vX.Y.Z` when you want a build that will not move.

Releases are cut per image by pushing a tag named `<image>/vX.Y.Z`, which builds
and publishes that image alone:

```sh
git tag node-agent/v1.0.0 && git push origin node-agent/v1.0.0
```

Base images and package versions are deliberately **not** pinned — rebuilding is
how upstream updates land, and the published tag is what pins things for whoever
pulls it.

## Adding an image

```sh
cp -r template images/my-image
```

1. Edit `images/my-image/Dockerfile`, or base it on an image already published
   here (`FROM gitea.libretechconsulting.com/rmcguire/node-agent:latest`).
2. Fill in `images/my-image/README.md`.
3. Extend `images/my-image/test.sh` to assert whatever the image promises.
4. `make build IMAGE=my-image`

CI needs no changes — it discovers every directory under `images/` that contains
a `Dockerfile`. See [AGENTS.md](AGENTS.md) for the full conventions.

## Local development

```sh
make help                   # list targets
make all                    # everything CI does
make build IMAGE=node-agent # build and smoke-test one image
```

## CI

Two Gitea workflows, both of which just call the `make` and `hack/` entry points
above, so a green `make all` locally means a green pipeline:

- **`lint.yaml`** — repository layout, `hadolint`, `shellcheck`.
- **`build.yaml`** — works out which images changed, then builds, smoke-tests and
  (on `main` or a release tag) publishes each one. Nothing is pushed until its
  smoke test passes.