--- 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 `.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/`: `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).