diff --git a/.gitea/workflows/publish-image.yml b/.gitea/workflows/publish-image.yml new file mode 100644 index 0000000..d1562ec --- /dev/null +++ b/.gitea/workflows/publish-image.yml @@ -0,0 +1,230 @@ +name: Publish image + +# Fires on the version tag release-please creates when the release PR is +# merged (vX.Y.Z, plain tags - see OKF_Nuxt/decisions/release-engineering.md). +# A push to main does NOT build: an image tag always maps to a released +# version, so what runs in the cluster is traceable to a release, not to an +# arbitrary commit. +on: + push: + tags: + - 'v*' + +# The runner has capacity 1, so releases already serialize. This keeps a +# manual re-run from racing a fresh release on the same tags. +concurrency: + group: publish-image + cancel-in-progress: false + +env: + # Registry host + repository path. The path segment is the Gitea + # organisation, so k3s pulls registry.noelsabia.dev/cv_website/nuxt:. + IMAGE: registry.noelsabia.dev/cv_website/nuxt + APP_DIR: . + +jobs: + publish: + name: Build and push image + # Dedicated label, NOT ubuntu-latest: this job needs the host Docker + # socket, and `docker_host` is a runner-wide setting. Sharing a label + # with pr-checker.yml would hand PR code (from a branch) a root- + # equivalent socket on the host that also runs Gitea and k3s. + # Register a second act_runner with `--labels publish:docker://node:22-bookworm` + # and `container.docker_host: automount` in its config, before the first + # tag: an unmatched label leaves the job queued indefinitely. + runs-on: publish + # A hung build would hold the capacity-1 runner and, through it, every + # other job on this server. Gitea's instance default is not a contract. + timeout-minutes: 20 + # Same base image as the other jobs. The build runs on the runner's + # Docker daemon (not in a nested daemon), so this container only needs + # the CLI - see OKF_Nuxt/decisions/registry-publishing.md. + container: node:22-bookworm + steps: + - uses: actions/checkout@v4 + + - name: Install Docker CLI + # Debian's docker.io, not a curl-piped binary from GitHub: apt is a + # signed channel, and bookworm ships an arm64 build. Only the client + # is needed; the daemon lives on the host. + run: | + apt-get update + apt-get install -y --no-install-recommends docker.io + docker --version + + - name: Check daemon access + # Fail here, with the cause, instead of halfway through a build. + # An unreachable daemon means the runner was started without the + # host socket mounted: set `docker_host: automount` in the + # act_runner config and restart the service. + # + # The socket is root-equivalent on the host, and automount is a + # runner-wide setting - it applies to every job on that runner, + # including PR jobs. Only enable it on a runner label that + # PR-triggered jobs cannot use; see the trust boundary in + # OKF_Nuxt/decisions/registry-publishing.md. + run: | + echo "DOCKER_HOST=${DOCKER_HOST:-}" + if ! docker info > /dev/null 2>&1; then + echo "::error::no Docker daemon reachable from this job - the act_runner needs the host Docker socket (docker_host: automount)" + exit 1 + fi + + - name: Resolve version and tags + id: version + run: | + # GITHUB_REF_NAME is the tag on a tag push. The git fallback keeps + # this working if a runner version does not set it. + version="${GITHUB_REF_NAME:-$(git describe --tags --exact-match HEAD)}" + # Strict semver, not a `v[0-9]*` prefix match: that would accept + # `v1`, `v1-anything` and prereleases, all valid registry tags. + if ! printf '%s' "$version" | grep -qE '^v[0-9]+\.[0-9]+\.[0-9]+$'; then + echo "::error::expected a vMAJOR.MINOR.PATCH tag, got '${version}'" + exit 1 + fi + sha="$(git rev-parse --short=12 HEAD)" + + # `latest` follows the newest release, not the newest build. A + # re-run of an older tag (Gitea can replay any run) must not drag + # `latest` backwards, while a re-run of the newest tag may set it: + # that release had not produced an image yet. + # A tag comparison needs the other tags, which a depth-1 tag + # checkout does not have. If the fetch fails, skip `latest` and + # say so - a wrong tag is worse than a missing one. + if git fetch --tags --force --quiet origin 2>/dev/null; then + newest="$(git tag -l | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -n 1)" + if [ "$version" = "$newest" ]; then + latest=true + else + latest=false + echo "::warning::${version} is not the newest release (${newest}) - not moving :latest" + fi + else + latest=false + echo "::warning::could not list tags - not moving :latest" + fi + + # Short SHA tag alongside the version: OKF_CV_Website/architecture/ + # delivery.md asks for SHA-tagged images so every deploy is + # traceable to a commit even after a tag is moved. + { + echo "version=${version}" + echo "sha=${sha}" + echo "latest=${latest}" + } >> "$GITHUB_OUTPUT" + echo "Building ${version} from ${sha} (latest: ${latest})" + + - name: Log in to the registry + env: + REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }} + REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }} + run: | + # Missing secrets must fail loudly: an anonymous `docker push` + # would answer 401 with a message most people misread as a + # missing repository. + [ -n "$REGISTRY_USERNAME" ] || { echo "::error::secret REGISTRY_USERNAME is empty"; exit 1; } + [ -n "$REGISTRY_PASSWORD" ] || { echo "::error::secret REGISTRY_PASSWORD is empty"; exit 1; } + printf '%s' "$REGISTRY_PASSWORD" \ + | docker login registry.noelsabia.dev -u "$REGISTRY_USERNAME" --password-stdin + + - name: Refuse to overwrite a published version + env: + REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }} + REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }} + VERSION: ${{ steps.version.outputs.version }} + run: | + # A version tag is immutable once published. Gitea can replay any + # run, and `docker push` would silently replace :vX.Y.Z with a + # rebuilt image, so the release would change content after the + # fact. A missing tag (first attempt, or a run that failed before + # pushing) is fine - nothing was published. + # + # Registry v2 API instead of `docker manifest inspect`: the + # Debian 20.10 client fails that command on OCI indexes with + # "unsupported manifest media type and no default available", + # for existing and missing tags alike. + url="https://registry.noelsabia.dev/v2/cv_website/nuxt/manifests/${VERSION}" + code=$(curl -s -o /dev/null -w '%{http_code}' \ + -u "${REGISTRY_USERNAME}:${REGISTRY_PASSWORD}" \ + -H 'Accept: application/vnd.docker.distribution.manifest.v2+json' \ + -H 'Accept: application/vnd.oci.image.index.v1+json' \ + -H 'Accept: application/vnd.oci.image.manifest.v1+json' \ + "$url") + echo "GET /v2/cv_website/nuxt/manifests/${VERSION}: HTTP ${code}" + case "$code" in + 200) echo "::error::${VERSION} is already published and version tags are immutable - delete that tag in the registry deliberately to replace it"; exit 1 ;; + 404) echo "${VERSION} is not published yet - continuing" ;; + 401|403) echo "::error::registry rejected the credentials (HTTP ${code}) - check REGISTRY_USERNAME/REGISTRY_PASSWORD"; exit 1 ;; + *) echo "::error::unexpected answer from the registry (HTTP ${code})"; exit 1 ;; + esac + + - name: Build image + env: + VERSION: ${{ steps.version.outputs.version }} + SHA: ${{ steps.version.outputs.sha }} + run: | + # --platform is explicit so a build on the wrong architecture fails + # instead of silently producing an amd64 image the arm64 node + # cannot run. Native here, no QEMU involved. + docker build \ + --platform linux/arm64 \ + --label "org.opencontainers.image.version=${VERSION}" \ + --label "org.opencontainers.image.revision=${SHA}" \ + -t "${IMAGE}:${VERSION}" \ + -t "${IMAGE}:sha-${SHA}" \ + "${APP_DIR}" + + - name: Smoke-test the image + env: + VERSION: ${{ steps.version.outputs.version }} + run: | + # Start the real server inside the built image and require a 2xx + # with a real SSR body, not an empty shell. Cheaper than + # publishing a broken release, and the only step that proves the + # Nitro output actually runs. Done inside the container because + # the app's port is not reachable from this job container - the + # daemon publishes on the host, not here. + # + # The size floor is deliberately loose: the rendered homepage was + # 97 kB on 2026-10-24, so 10 kB catches "200 but nothing rendered" + # without failing on a future copy change. + docker run --rm "${IMAGE}:${VERSION}" sh -c ' + node .output/server/index.mjs & + server=$! + i=0 + while [ "$i" -lt 30 ]; do + if out=$(node -e "fetch(\"http://127.0.0.1:3000/\").then(async r => { const body = await r.text(); if (!r.ok || body.length < 10000) process.exit(1); console.log(r.status + \" \" + body.length + \" bytes\") }).catch(() => process.exit(1))" 2>/dev/null); then + echo "homepage rendered after ${i}s: HTTP ${out}" + kill "$server" + exit 0 + fi + i=$((i + 1)) + sleep 1 + done + echo "no 2xx homepage with a rendered body within 30s" + kill "$server" + exit 1 + ' + + - name: Tag latest + if: steps.version.outputs.latest == 'true' + env: + VERSION: ${{ steps.version.outputs.version }} + run: docker tag "${IMAGE}:${VERSION}" "${IMAGE}:latest" + + - name: Push image + env: + VERSION: ${{ steps.version.outputs.version }} + SHA: ${{ steps.version.outputs.sha }} + LATEST: ${{ steps.version.outputs.latest }} + run: | + # Explicit per tag, not `--all-tags`: --all-tags would also push + # stale local tags left on the shared daemon by earlier runs. + docker push "${IMAGE}:${VERSION}" + docker push "${IMAGE}:sha-${SHA}" + if [ "$LATEST" = "true" ]; then + docker push "${IMAGE}:latest" + echo "Pushed ${IMAGE}:${VERSION}, :sha-${SHA}, :latest" + else + echo "Pushed ${IMAGE}:${VERSION}, :sha-${SHA} (:latest untouched)" + fi diff --git a/.github/actionlint.yaml b/.github/actionlint.yaml new file mode 100644 index 0000000..2f95d68 --- /dev/null +++ b/.github/actionlint.yaml @@ -0,0 +1,9 @@ +# actionlint configuration. +# +# `publish` is the label of the second act_runner registration (the one with +# the host Docker socket). actionlint only knows GitHub's hosted labels, so +# custom self-hosted labels have to be declared here or every workflow using +# them fails the lint hook. +self-hosted-runner: + labels: + - publish diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index def6e07..6883340 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -55,6 +55,12 @@ repos: hooks: - id: actionlint files: \.gitea/workflows/.*\.ya?ml$ + # actionlint only auto-loads its config when the file is + # .github/actionlint.yaml *and* it recognises a project root by + # .github/workflows, which this repo does not have (it uses + # .gitea/workflows). Pass the config explicitly, or the custom + # `publish` runner label is reported as unknown. + args: [-config-file, .github/actionlint.yaml] # --------------------------------------------------------- ESLint (Nuxt) - # Local hook: needs `pnpm install` to have run in this repo. --fix makes diff --git a/OKF_Nuxt/decisions/index.md b/OKF_Nuxt/decisions/index.md index 92e9a87..283681c 100644 --- a/OKF_Nuxt/decisions/index.md +++ b/OKF_Nuxt/decisions/index.md @@ -5,6 +5,7 @@ * [Vulnerability audit policy](vulnerability-audit-policy.md) - Blocking audit, reviewed ignore-list for unfixable advisories, and the pnpm-11 settings home. * [Release engineering](release-engineering.md) - release-please in manifest mode, conventional commits as input, message format enforced at commit time. * [Snyk paused and secrets policy](snyk-paused-and-secrets-policy.md) - Why the job is skipped rather than deleted, and the token scopes every workflow secret needs. +* [Publishing images to the own registry](registry-publishing.md) - A release tag builds and pushes to registry.noelsabia.dev; main pushes do not build. * [Dev container shape](dev-container-shape.md) - The source is bind-mounted into a container that already holds the dependencies, and the dev server runs as the image's `node` user. * [Build layer order](build-layer-order.md) - Why the manifests are copied before the source, and what invalidates what. * [Build context filter](build-context-filter.md) - What `.dockerignore` may exclude, and the one thing it must never exclude. diff --git a/OKF_Nuxt/decisions/registry-publishing.md b/OKF_Nuxt/decisions/registry-publishing.md new file mode 100644 index 0000000..3693d1e --- /dev/null +++ b/OKF_Nuxt/decisions/registry-publishing.md @@ -0,0 +1,171 @@ +--- +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). diff --git a/OKF_Nuxt/index.md b/OKF_Nuxt/index.md index 6de6d07..41f2d09 100644 --- a/OKF_Nuxt/index.md +++ b/OKF_Nuxt/index.md @@ -23,6 +23,7 @@ config files — the configs say what, these documents say why. * [Vulnerability audit policy](decisions/vulnerability-audit-policy.md) - Blocking audit; reviewed ignore-list for unfixable advisories in pnpm-workspace.yaml. * [Release engineering](decisions/release-engineering.md) - release-please in manifest mode; conventional commits enforced at commit time. * [Snyk paused and secrets policy](decisions/snyk-paused-and-secrets-policy.md) - Quota-paused job kept in place; `write:issue` scope required on every workflow token. +* [Publishing images to the own registry](decisions/registry-publishing.md) - A release tag builds the image and pushes it to registry.noelsabia.dev; the runner socket it needs is root-equivalent and belongs on a separate label. ## Docker and development environment diff --git a/OKF_Nuxt/log.md b/OKF_Nuxt/log.md index 72ae696..19c94ad 100644 --- a/OKF_Nuxt/log.md +++ b/OKF_Nuxt/log.md @@ -1,5 +1,11 @@ # Update Log +## 2026-10-24 (release publishes an image) + +* **Creation**: [publish-image.yml](../.gitea/workflows/publish-image.yml) - a `vX.Y.Z` tag push builds `Dockerfile` on the arm64 runner and pushes `registry.noelsabia.dev/cv_website/nuxt` as the version and `sha-<12>`, plus `latest` when that tag is the newest release. Main pushes deliberately do not build: the registry holds releases, not commits. The job uses the runner's own Docker daemon (client only in the `node:22-bookworm` container), so the act_runner needs `container.docker_host: automount`; the first step fails with that cause if it is missing. That socket is root-equivalent, so it may only sit on a label PR jobs cannot use - recorded under the trust boundary in [Publishing images to the own registry](decisions/registry-publishing.md). Repo secrets: `REGISTRY_USERNAME`, `REGISTRY_PASSWORD`. +* **Review follow-up** (PR #19, 1 BLOCKER + 4 WARN + 2 NIT): applied the strict `vMAJOR.MINOR.PATCH` check, the newest-release rule for `latest`, a smoke test that starts the image and requires 2xx on `/`, and `timeout-minutes: 20`. Rejected with evidence: the `.dockerignore` leak (`.env*`, `*.pem`, `.git` are excluded) and the Docker-client/daemon API mismatch (20.10.24 client against a 29.9.2 daemon built successfully over the socket). +* **Second review follow-up** (PR #19): the job now runs on the dedicated `publish` label instead of `ubuntu-latest`, so the host socket it needs can never be shared with PR jobs - the earlier version required a runner configuration its own trust boundary forbade. Added the immutability guard (registry v2 `manifests/`: `200` aborts, `404` continues) after measuring that `docker manifest inspect` fails on OCI indexes with the pinned 20.10 client; the smoke test now also requires a rendered body (10 kB floor) rather than a bare 2xx. `.github/actionlint.yaml` declares the custom label, and the hook passes it with `-config-file` because this repo keeps workflows in `.gitea/`. + ## 2026-10-23 (profile data in the terminal) * **Creation**: [Profile data](profile.md) - imported the LinkedIn export `Profile.pdf` into `app/data/chapters.ts`: PreZero active; Defifort, Alignerr, Outlier, freelance and 42 finished. Each row carries a context label (Enterprise, Web3 startup, AI Developer, Freelance, Education). The terminal now shows 1 active / 5 sealed / 14 rebounds; the export has no entry for `dreambit`, `ongoing-studies` or `apprenticeship`, so those rows are gone. `uptime` and `rebounds` remain mock. * **Update**: [backend endpoints](backend-endpoints.md) - examples and totals now match the real six-chapter list; the source frontmatter points at the export.