Files
CV_Site_Nuxt/OKF_Nuxt/decisions/registry-publishing.md
T
Noel Sabia 5f7027bd86
PR Check / Security scan (Snyk) (pull_request) Skipped
PR Check / Lint + typecheck (pull_request) Failing after 22s
PR Check / Secret scan (gitleaks) (pull_request) Successful in 6s
PR Check / Dependency audit (pull_request) Failing after 9s
PR Check / Dockerfile lint (droast) (pull_request) Successful in 5s
PR Check / AI code review (opencode) (pull_request) Failing after 13s
docs: record that the registry is Gitea's built-in container registry
Verified by logging in to registry.noelsabia.dev and pushing by hand.
The registry is Gitea's own, not a separately deployed component, so
there is nothing to stand up or reinvent.
2026-10-31 18:56:56 +01:00

184 lines
9.0 KiB
Markdown

---
type: Decision
title: Publishing images to the own registry
description: A release tag builds the production image and pushes it to registry.noelsabia.dev, because that is the only way Kubernetes can pull it.
tags: [decision, ci, docker, registry, gitea-actions]
status: draft
generated: { by: opencode-go/deepseek-v4.1-flash, at: 2026-10-24T00:00:00Z }
verified: { by: human:noel, at: not yet }
sources:
- id: workflow
resource: .gitea/workflows/publish-image.yml
title: Publish image workflow
- id: dockerfile
resource: Dockerfile
title: Production Dockerfile
- id: k8s
resource: ../OKF_CV_Website/architecture/delivery.md
title: Sibling bundle - image tags and registry pull
---
# Decision
**The registry is Gitea's own, and that is the default.** Gitea ships a
built-in container registry per owner/organisation
([docs.gitea.com - container](https://docs.gitea.com/usage/packages/container/)).
`registry.noelsabia.dev` is that registry: the `/cv_website/` path segment
is the Gitea organisation, images live under the package of the
repository that pushed them. Verified 2026-10-31 - Noel logged in with
`docker login registry.noelsabia.dev` and can push. There is nothing to
stand up and nothing to reinvent: no separate Registry/Harbor
deployment, no extra hosting, TLS is already handled by the same server
that serves Gitea. The publishing workflow exists only to automate
pushes to this built-in registry.
`.gitea/workflows/publish-image.yml` builds `Dockerfile` and pushes the
result to the own registry:
```
registry.noelsabia.dev/cv_website/nuxt:v1.2.3
registry.noelsabia.dev/cv_website/nuxt:sha-<12-char-sha>
registry.noelsabia.dev/cv_website/nuxt:latest # newest release only
```
**Trigger is the release tag, not the main push.** release-please creates
`vX.Y.Z` when the release PR is merged ([release
engineering](release-engineering.md)); that tag push is the build. A main
push would otherwise publish commits that no release describes, and
`latest` would move on work in progress.
# Why not build on every main push
* The registry is the deployment channel. Every image in it should answer
"which release is this", and a tagged commit does.
* The runner has capacity 1 and shares 2 vCPU / 4 GB with Gitea and k3s
(`OKF_CV_Website/architecture/server-budget.md`). A Nuxt image build can
take over 1 GB; running it more often than a release buys nothing.
* The PR checks already gate the code that becomes a release. A tag build
is not the first time the tree is built - a failing build here is a
packaging failure, not a surprise.
# Why docker-outside-of-docker
The job runs in `node:22-bookworm`, like every other job in this
repository, and only needs the Docker client: `docker build` sends the
build context over the socket, so the daemon never reads the container's
filesystem. That requires the act_runner to mount its host socket:
```yaml
# act_runner config.yaml
container:
docker_host: automount
```
Without it the `Check daemon access` step fails first with a named cause
instead of a mid-build error. The alternative - a privileged `docker:dind`
sidecar - needs privileged mode and a second daemon per release; not worth
it on this server.
## Trust boundary (the cost of the socket)
A mounted Docker socket is **root-equivalent on the host**: any job that
has it can run `docker run -v /:/host` and read or write anything, which on
this machine means Gitea's data, k3s, and the CV itself. `docker_host` is a
**runner-wide** setting, so enabling it gives the socket to every job on
that runner, including PR jobs whose code comes from a branch.
Therefore the rule: **the socket only ever goes on a runner label that
PR-triggered jobs do not use.**
The workflow follows it by scheduling onto a dedicated label:
```yaml
runs-on: publish # NOT ubuntu-latest, which pr-checker.yml uses
```
That label only exists once a second act_runner registration is configured
with `container.docker_host: automount` and, for example,
`--labels publish:docker://node:22-bookworm`. Until then the job queues
without starting, and `timeout-minutes` does not apply to a job that never
starts - register the runner before the first release tag.
Not acceptable: adding `automount` to the shared `ubuntu-latest` runner.
That hands PR code a root-equivalent socket on the host that also runs
Gitea and k3s. If it is ever the only option, treat it as an accepted risk
and record it here rather than letting the workflow imply it.
# Why `--platform linux/arm64`
The runner and the node are the same arm64 machine, so the build is native
(no QEMU, no crossed dependencies). Stating the platform makes a build on
another architecture fail instead of publishing an image the node cannot
run.
# Secrets
| Gitea secret | Use |
|---|---|
| `REGISTRY_USERNAME` | basic-auth user for `docker login registry.noelsabia.dev` |
| `REGISTRY_PASSWORD` | basic-auth password (or token) for the same login |
Both are repo secrets. The login uses `--password-stdin` so the value never
appears in the process list or the log.
# Before the first release tag
1. Repo secrets `REGISTRY_USERNAME` and `REGISTRY_PASSWORD` exist.
2. A runner with the `publish` label exists and its config has
`container.docker_host: automount`. Without the label the job queues
forever; without the socket it fails at `Check daemon access`.
3. `pr-checker.yml` still runs on a label whose runner has no socket.
4. Namespace `cv` has an `imagePullSecret` for the same credentials.
5. `registry.noelsabia.dev` answers over HTTPS.
# Guards in the workflow
| Guard | Why |
|---|---|
| Strict `^vMAJOR.MINOR.PATCH$` check | A `v[0-9]*` prefix match accepts `v1`, `v1-anything` and `v1.2.3-rc1`, all of which are valid registry tags and would publish silently |
| `latest` only when the built tag is the highest `vX.Y.Z` in the repository | Gitea can replay any run. Without the comparison, re-running `v1.2.0` after `v1.3.0` drags `latest` backwards. A re-run of the newest tag still moves it - that release had not produced an image yet. If the tag list cannot be fetched, `latest` is skipped with a warning rather than guessed |
| A published version tag is never overwritten | Before building, the registry's v2 API is asked for `manifests/<version>`: `200` aborts the run, `404` continues. A replay of a released tag fails instead of silently replacing published content. `docker manifest inspect` is deliberately *not* used - the Debian 20.10 client fails it on OCI indexes with `unsupported manifest media type and no default available`, for existing and missing tags alike |
| Smoke test before any push | The image is started and must answer 2xx with at least 10 kB of rendered HTML on `/` (the real page is ~97 kB), so "200 but nothing rendered" fails too. Port publishing is not usable here: the daemon binds on the host, not in the job container |
| `timeout-minutes: 20` | A hung build would hold the capacity-1 runner and every job queued behind it |
| `.github/actionlint.yaml` | Declares the custom `publish` label, otherwise the lint hook reports it as unknown. The hook passes the file with `-config-file`, because actionlint only auto-loads it when it recognises a `.github/workflows` project |
# Costs and consequences
* **Registry storage grows** by one image per release in three tags. The
three tags share layers, so the extra cost is mostly the tag, not the
bytes.
* **Images accumulate on the runner's daemon** (`sha-`, version and
`latest` tags). Pruning is not part of this change; add a
`docker image prune` policy when the disk usage actually matters.
* **`latest` is a convenience, not a pin.** Manifests should reference the
version or SHA tag so a release rollback is a manifest edit.
* **k3s needs pull credentials**: an `imagePullSecret` in the namespace for
the same basic-auth pair, or `/etc/rancher/k3s/registries.yaml` if the
registry is ever plain HTTP. Not part of this workflow.
# Not verified
* That the runner has the host socket mounted (`docker_host: automount`) -
the workflow's first step answers this on the first release.
* That the arm64 build succeeds: `Dockerfile` has been built on x86_64
only ([production image](production-image.md)).
* That the smoke test passes on arm64. The same script was run against an
x86_64 build of the merged tree and answered 2xx; the arm64 run is the
first release.
* That `registry.noelsabia.dev` is reachable over HTTPS from the runner.
A plain-HTTP endpoint fails `docker login` with `server gave HTTP
response to HTTPS client` and needs `insecure-registries` on the daemon
plus `registries.yaml` on k3s.
* Whether Gitea runs a `pull_request` workflow from a fork without
maintainer approval on this instance. That answer decides how severe the
socket risk above really is.
# Revisit when
* A second image (the Go gateway or chapter service) needs publishing -
then the workflow grows a matrix instead of being copied.
* Deploys should follow automatically: the release workflow gains a
`kubectl set image` step, or manifests start referencing the SHA tag.
* Multi-arch becomes necessary (a laptop or a CI host of the other
architecture pulls the image).