--- 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.** Two acceptable layouts: * a second act_runner registration with `docker_host: automount` and a distinct label (e.g. `publish`), used only by this workflow; or * one runner, but this workflow moved to the dedicated label and `pr-checker.yml` left on a label without the socket. Not acceptable: adding `automount` to the single shared runner while `pr-checker.yml` runs on it. If that is the only option, treat it as an accepted risk and record it here - the trade is "PR code can become root on the host" against "images can be built at all". # 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. # 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 | | Smoke test before any push | The image is started and must answer 2xx on `/` from inside the container. Build success only proves the bundle compiled. 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 | # 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).