diff --git a/.gitea/workflows/build.yaml b/.gitea/workflows/build.yaml new file mode 100644 index 0000000..e78778c --- /dev/null +++ b/.gitea/workflows/build.yaml @@ -0,0 +1,174 @@ +# Build the container image and publish it to this Gitea instance's +# registry. +# +# Gitea serves its container registry on the same host as the web UI, so +# the image lands at git.clortox.com/tyler/rss-to-opds. That host is +# derived from github.server_url rather than hardcoded, so this keeps +# working if the instance moves or the repository is forked. Set a +# repository variable named CONTAINER_REGISTRY to override it (for a +# separate registry host). +# +# Only actions/checkout is used. The build is plain docker rather than +# the buildx and login actions, so a job never has to reach the internet +# to fetch third-party actions -- which is the most common way a +# self-hosted runner fails. +# +# Two requirements on the runner, both documented in README.md: +# +# * Docker must be usable from the job. For a typical act_runner that +# means mounting /var/run/docker.sock into the job container. The +# guard step below fails with a clear message rather than a +# confusing one. +# * The token must be allowed to write packages. Gitea's automatic +# token usually is; if a push is refused for permissions, create a +# personal access token with the `write:package` scope and save it +# as the REGISTRY_TOKEN secret. This workflow prefers that secret +# whenever it is set. +name: build + +on: + push: + branches: + - master + tags: + - "*" + pull_request: + branches: + - master + # Lets the image be rebuilt by hand from the Gitea UI. + workflow_dispatch: + +env: + # The default branch: the only one that also moves `latest`. + DEFAULT_BRANCH: master + +jobs: + container: + runs-on: ubuntu-latest + steps: + - name: Check out the repository + uses: actions/checkout@v4 + + # Fail early and legibly: without this, a runner missing Docker + # produces a bare "docker: not found" from whichever step runs. + - name: Check that docker is available + run: | + if ! command -v docker >/dev/null 2>&1; then + echo "::error::docker is not available in this job. On" + echo "act_runner, give the job the host socket, for example:" + echo "-v /var/run/docker.sock:/var/run/docker.sock" + exit 1 + fi + docker version + + # The gate. The Dockerfile's first stage runs the whole suite, so a + # failing test stops the image from being built or pushed at all. + # Nothing from that stage reaches the published image. + - name: Run the test suite as a build stage + run: docker build --target test . + + # Exported through GITHUB_ENV rather than step outputs: fewer moving + # parts, and it works on any Gitea version. + - name: Work out the registry, image name and tags + run: | + set -eu + + registry="${CONTAINER_REGISTRY:-}" + if [ -z "$registry" ]; then + # https://git.clortox.com/ -> git.clortox.com + registry="$(printf '%s' "${GITHUB_SERVER_URL:-}" | + sed -E 's#^[a-zA-Z]+://##; s#/+$##')" + fi + if [ -z "$registry" ]; then + echo "::error::cannot determine the registry host; set a" + echo "repository variable named CONTAINER_REGISTRY" + exit 1 + fi + + # Docker wants a lowercase repository path; usernames may not be. + path="$(printf '%s' "${GITHUB_REPOSITORY:-}" | + tr '[:upper:]' '[:lower:]')" + + # Branch and tag names can hold characters a docker tag cannot + # ("feature/x", for instance), and a tag may not begin with + # "." or "-". + ref_name="${GITHUB_REF_NAME:-manual}" + safe_ref="$(printf '%s' "$ref_name" | + sed -E 's#[^A-Za-z0-9_.-]+#-#g; s#^[.-]+##')" + [ -n "$safe_ref" ] || safe_ref="manual" + + # Always tag the immutable revision, so any image can be traced + # back to the commit it was built from. + sha="$(printf '%s' "${GITHUB_SHA:-0000000}" | cut -c1-7)" + tags="sha-$sha" + + case "${GITHUB_REF:-}" in + refs/tags/*) + tags="$safe_ref latest $tags" + ;; + *) + if [ "$ref_name" = "${DEFAULT_BRANCH:-master}" ]; then + tags="$safe_ref latest $tags" + else + tags="$safe_ref $tags" + fi + ;; + esac + + { + echo "REGISTRY=$registry" + echo "IMAGE=$registry/$path" + echo "TAGS=$tags" + echo "VERSION=$safe_ref" + } >> "$GITHUB_ENV" + + if [ -n "${GITHUB_STEP_SUMMARY:-}" ]; then + printf 'image: %s\ntags: %s\n' "$registry/$path" "$tags" \ + >> "$GITHUB_STEP_SUMMARY" + fi + echo "will build $registry/$path with tags: $tags" + + # Nothing is pushed for a pull request: a fork should never be able + # to publish an image into this registry. + - name: Log in to the registry + if: github.event_name != 'pull_request' + run: | + set -eu + token="${REGISTRY_TOKEN:-${GITHUB_TOKEN:-}}" + if [ -z "$token" ]; then + echo "::error::no registry token available; set a" + echo "REGISTRY_TOKEN secret (scope: write:package)" + exit 1 + fi + printf '%s' "$token" | + docker login "$REGISTRY" \ + --username "${{ github.actor }}" --password-stdin + + - name: Build without pushing (pull requests) + if: github.event_name == 'pull_request' + run: | + set -eu + number="${{ github.event.pull_request.number }}" + docker build --tag "$IMAGE:pr-$number" . + echo "built $IMAGE:pr-$number (not pushed)" + + - name: Build and push + if: github.event_name != 'pull_request' + run: | + set -eu + + # Every tag is applied in one build, so the layers build once. + # The unquoted expansion is deliberate: $TAGS is a list. + tag_args="" + for tag in $TAGS; do + tag_args="$tag_args --tag $IMAGE:$tag" + done + docker build $tag_args . + + for tag in $TAGS; do + docker push "$IMAGE:$tag" + echo "pushed $IMAGE:$tag" + done + + count="$(printf '%s' "$TAGS" | wc -w)" + echo "done: $count tag(s), latest is $VERSION" diff --git a/.gitignore b/.gitignore index ab2d846..c401a13 100644 --- a/.gitignore +++ b/.gitignore @@ -20,6 +20,9 @@ venv/ htmlcov/ *.epub +# pi session artifacts (task output from background commands) +.pi/ + # Editors .idea/ .vscode/ diff --git a/.pi/tasks/01a1e156-4fa0-722f-83e8-c971d55b7a0e-2566715/b880b783d.json b/.pi/tasks/01a1e156-4fa0-722f-83e8-c971d55b7a0e-2566715/b880b783d.json deleted file mode 100644 index 01d1cb4..0000000 --- a/.pi/tasks/01a1e156-4fa0-722f-83e8-c971d55b7a0e-2566715/b880b783d.json +++ /dev/null @@ -1,29 +0,0 @@ -{ - "id": "b880b783d", - "name": "Docker image build", - "command": "cd /media/git/odps-from-rss && docker build -t opds-from-rss:latest . 2>&1", - "description": "Build the container image to verify the zero-dependency Dockerfile works end to end.", - "status": "completed", - "outputPath": ".pi/tasks/01a1e156-4fa0-722f-83e8-c971d55b7a0e-2566715/b880b783d.output", - "cwd": "/media/git/odps-from-rss", - "startTime": 1794783944805, - "endTime": 1794783954328, - "exitCode": 0, - "signal": null, - "pid": 2607703, - "bytesWritten": 3628, - "isAgent": false, - "surviveReload": false, - "notified": true, - "notifyOnCompletion": true, - "triggerOnCompletion": true, - "timeoutSeconds": 900, - "shellPolicy": { - "policy": "inherit", - "executable": "/bin/bash", - "argvPrefix": [ - "-c" - ], - "dialect": "bash" - } -} diff --git a/.pi/tasks/01a1e156-4fa0-722f-83e8-c971d55b7a0e-2566715/b880b783d.output b/.pi/tasks/01a1e156-4fa0-722f-83e8-c971d55b7a0e-2566715/b880b783d.output deleted file mode 100644 index 23f370c..0000000 --- a/.pi/tasks/01a1e156-4fa0-722f-83e8-c971d55b7a0e-2566715/b880b783d.output +++ /dev/null @@ -1,76 +0,0 @@ -#0 building with "default" instance using docker driver - -#1 [internal] load build definition from Dockerfile -#1 transferring dockerfile: -#1 transferring dockerfile: 1.07kB done -#1 DONE 0.2s - -#2 [internal] load metadata for docker.io/library/python:3.13-alpine -#2 DONE 1.2s - -#3 [internal] load .dockerignore -#3 transferring context: -#3 transferring context: 139B done -#3 DONE 0.2s - -#4 [internal] load build context -#4 ... - -#5 [1/5] FROM docker.io/library/python:3.13-alpine@sha256:9ef1a599f863231c3d91e941389bfdc4a2d6070557243d54df1a4e57015b960e -#5 resolve docker.io/library/python:3.13-alpine@sha256:9ef1a599f863231c3d91e941389bfdc4a2d6070557243d54df1a4e57015b960e 0.4s done -#5 DONE 0.4s - -#4 [internal] load build context -#4 transferring context: 491.01kB done -#4 DONE 0.6s - -#5 [1/5] FROM docker.io/library/python:3.13-alpine@sha256:9ef1a599f863231c3d91e941389bfdc4a2d6070557243d54df1a4e57015b960e -#5 DONE 1.1s - -#5 [1/5] FROM docker.io/library/python:3.13-alpine@sha256:9ef1a599f863231c3d91e941389bfdc4a2d6070557243d54df1a4e57015b960e -#5 extracting sha256:881fc932939efef04ca120ad44bbd2c0917851eb247aa4995428afb1e80ede17 -#5 sha256:17af2db0edc9c7ff966b9f7e8424caed1203bc5cec5e3c061f3516ef5b8d9ece 248B / 248B 0.1s done -#5 extracting sha256:881fc932939efef04ca120ad44bbd2c0917851eb247aa4995428afb1e80ede17 0.3s done -#5 sha256:f9abc654947e09e316e7703544bd7e68123d383aeb70c5a9cf15be03e71721ce 0B / 12.67MB 0.2s -#5 sha256:ce6949f6b5329553c2f3fc626421da4f70d633cfddb6ad2227f3ac0b7205bd8f 0B / 412.00kB 0.2s -#5 sha256:f9abc654947e09e316e7703544bd7e68123d383aeb70c5a9cf15be03e71721ce 4.19MB / 12.67MB 0.3s -#5 sha256:ce6949f6b5329553c2f3fc626421da4f70d633cfddb6ad2227f3ac0b7205bd8f 412.00kB / 412.00kB 0.2s done -#5 extracting sha256:ce6949f6b5329553c2f3fc626421da4f70d633cfddb6ad2227f3ac0b7205bd8f -#5 sha256:f9abc654947e09e316e7703544bd7e68123d383aeb70c5a9cf15be03e71721ce 12.67MB / 12.67MB 0.5s done -#5 extracting sha256:ce6949f6b5329553c2f3fc626421da4f70d633cfddb6ad2227f3ac0b7205bd8f 0.2s done -#5 DONE 1.7s - -#5 [1/5] FROM docker.io/library/python:3.13-alpine@sha256:9ef1a599f863231c3d91e941389bfdc4a2d6070557243d54df1a4e57015b960e -#5 extracting sha256:f9abc654947e09e316e7703544bd7e68123d383aeb70c5a9cf15be03e71721ce -#5 extracting sha256:f9abc654947e09e316e7703544bd7e68123d383aeb70c5a9cf15be03e71721ce 0.3s done -#5 DONE 2.0s - -#5 [1/5] FROM docker.io/library/python:3.13-alpine@sha256:9ef1a599f863231c3d91e941389bfdc4a2d6070557243d54df1a4e57015b960e -#5 extracting sha256:17af2db0edc9c7ff966b9f7e8424caed1203bc5cec5e3c061f3516ef5b8d9ece 0.1s done -#5 DONE 2.1s - -#6 [2/5] RUN apk add --no-cache ca-certificates && adduser -D -u 10001 -h /srv app -#6 0.739 OK: 11.4 MiB in 29 packages -#6 DONE 1.0s - -#7 [3/5] WORKDIR /srv -#7 DONE 0.3s - -#8 [4/5] COPY app/ ./app/ -#8 DONE 0.3s - -#9 [5/5] COPY config.example.json ./ -#9 DONE 0.3s - -#10 exporting to image -#10 exporting layers -#10 exporting layers 1.6s done -#10 exporting manifest sha256:701ef954b346b1f95b3ce1975be05310709337bda6897169db926e7ce7e93d18 0.1s done -#10 exporting config sha256:b098ef38aca29a44c9e971d5f7e128f7bb3dc43e4711f916fa24ad042ec443a1 0.1s done -#10 exporting attestation manifest sha256:0bdcacb0668771798a65cf1b8fa04c1460748786ea2b9d166b1436a416750f34 0.1s done -#10 exporting manifest list sha256:28c19d6010bbc1d8452a93d32e1ad8aa1e8f96b9a5e2d147bf93e99f4ac29f24 -#10 exporting manifest list sha256:28c19d6010bbc1d8452a93d32e1ad8aa1e8f96b9a5e2d147bf93e99f4ac29f24 0.1s done -#10 naming to docker.io/library/opds-from-rss:latest 0.0s done -#10 unpacking to docker.io/library/opds-from-rss:latest -#10 unpacking to docker.io/library/opds-from-rss:latest 0.8s done -#10 DONE 2.9s diff --git a/Dockerfile b/Dockerfile index e3ed8cf..6616737 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,3 +1,23 @@ +# ---- test stage ---------------------------------------------------------- +# Runs the suite inside the build, so a pipeline can gate the published image +# on it without needing Python on the runner: docker build --target test . +# +# A plain `docker build .` does not build this stage, and nothing from here +# reaches the runtime image -- the tests are never copied into it. +FROM python:3.13-alpine AS test +WORKDIR /src +COPY app/ ./app/ +COPY tests/ ./tests/ +COPY tools/ ./tools/ +# One test asserts that the shipped example configuration loads, so the suite +# needs it at the repository root, exactly as it sits in a working tree. +COPY config.example.json ./ +ENV PYTHONDONTWRITEBYTECODE=1 +# Deliberately not piped into `tail`: a pipeline reports the exit status of its +# last command, so the gate would pass even when the tests failed. +RUN python -m unittest discover -s tests -t . + +# ---- runtime stage ------------------------------------------------------- # The whole server is the Python standard library, so the image needs no build # toolchain, no wheels and no virtual environment -- just an interpreter, a trust # store for upstream TLS, and the code. diff --git a/Makefile b/Makefile index 6c978a6..bfe1b53 100644 --- a/Makefile +++ b/Makefile @@ -5,10 +5,11 @@ CONFIG ?= config.json IMAGE ?= opds-from-rss:latest PYTHON ?= python3 -.PHONY: help test run check demo demo-up demo-down build up down logs shell hash-password lint clean +.PHONY: help test test-docker run check demo demo-up demo-down build up down logs shell hash-password lint clean help: @echo "make test run the test suite (no dependencies needed)" + @echo "make test-docker run the suite inside the build (what CI gates on)" @echo "make run run the server locally with $(CONFIG)" @echo "make check validate $(CONFIG) and print the effective settings" @echo "make hash-password print the sha256 digest for auth.users[].password_sha256" @@ -25,6 +26,11 @@ help: test: $(PYTHON) -m unittest discover -s tests -t . -v +# The same suite, run the way the CI pipeline runs it. The Dockerfile's +# test stage is what gates the published image, so this checks that gate. +test-docker: + docker build --target test . + lint: $(PYTHON) -m compileall -q app tests tools @echo "sources compile cleanly" diff --git a/README.md b/README.md index 6c46856..361c535 100644 --- a/README.md +++ b/README.md @@ -191,6 +191,63 @@ that on a network you trust. service is directly reachable, so a spoofed `Host` header cannot shape the links in the catalog. +## Continuous integration + +`.gitea/workflows/build.yaml` runs on every push to `master`, on tags, and on +pull requests. It does three things: + +1. **Gates on the test suite.** The Dockerfile's first stage runs all 276 tests, so + a failing test stops the image from being built or pushed at all. +2. **Builds with plain `docker`** rather than the buildx and login actions, so a + job never has to reach the internet to fetch third-party actions. +3. **Pushes to this Gitea instance's registry**, which lives on the same host as the + web UI: + + ```sh + docker pull git.clortox.com/tyler/rss-to-opds:latest + ``` + +Tags published are `latest`, the branch or git tag name (only `master` moves +`latest`), and an immutable `sha-` on every build, so any image can be traced +back to its commit. Pull requests build but never push, so a fork cannot publish +into the registry. + +The same gate runs locally: + +```sh +make test-docker # docker build --target test . +make test # the same suite, without docker +``` + +### Runner requirements + +* **Docker must be usable from the job.** For a typical `act_runner` that means + giving the job container the host socket, in the runner's `config.yaml`: + + ```yaml + runner: + container: + options: "-v /var/run/docker.sock:/var/run/docker.sock" + ``` + + Without it, the workflow's guard step fails with that instruction rather than a + confusing `docker: not found`. +* **The token must be allowed to write packages.** Gitea's automatic token usually + is. If a push is refused for permissions, create a personal access token with the + `write:package` scope and save it as the `REGISTRY_TOKEN` repository secret — the + workflow prefers that secret whenever it is set. + +Two deliberate choices worth knowing about. The registry host is derived from +`github.server_url` instead of being hardcoded, so the workflow survives the +instance moving or the repository being forked; set a `CONTAINER_REGISTRY` +repository variable to point at a different registry. And `actions/checkout` is +referenced by tag rather than pinned to a commit SHA, which is the usual +convenience-for-reproducibility trade-off on a self-hosted runner. To pin it: + +```sh +git ls-remote https://github.com/actions/checkout refs/tags/v4 +``` + ## Development ```sh