ci(deploy): retrigger after host LIBRENOTES_IMAGE seed

The deploy workflow is now a single job that builds, pushes, and
deploys in one runner. Tag computation moved to docker/metadata-action,
the per-deploy .env perl rewrite is gone (host pins LIBRENOTES_IMAGE
once; main pushes update :main rolling, releases pin to :vX.Y.Z by
manual edit), and both jobs run in our bespoke runner image whose
runner user already has socket access via group membership.

ci.yml moves to the same image so go/make/node are all available
without per-step apt installs.

Drops compose.prod.yaml (unused, redundant with compose.netcup.yaml).

.env.netcup.example

@@ -1,5 +1,12 @@
 # Server-side .env for netcup deploy. Copy to /srv/librenotes/.env on the host.
-# Used by: docker compose -f docker-compose.yml -f compose.netcup.yaml up -d --build
+# Used by: docker compose -f compose.yaml -f compose.netcup.yaml up -d
+
+# Image to pull. The default `:main` rolls forward — main pushes
+# rebuild and push the same tag, so `compose pull` picks up the new
+# digest without rewriting this file. To pin a release (or roll back),
+# edit this line to an immutable tag such as :v0.1.0 and re-run
+# `docker compose -f compose.yaml -f compose.netcup.yaml pull && up -d`.
+LIBRENOTES_IMAGE=git.librete.ch/public/librenotes:main
 
 # Public origin (caddy reverse-proxies to librenotes:8080)
 LIBRENOTES_BASE_URL=https://ln.cloud.librete.ch

.gitea/workflows/ci.yml

@@ -9,6 +9,10 @@ on:
 jobs:
   ci:
     runs-on: ubuntu-latest
+    # Bespoke runner image (Ubuntu 24.04 + make + git + node + go via
+    # actions/setup-go). See git.librete.ch/libretech/runner-image.
+    container:
+      image: git.librete.ch/libretech/runner-image:v1
     timeout-minutes: 5
     steps:
       - name: Checkout

.gitea/workflows/deploy.yml

@@ -6,94 +6,91 @@ on:
     tags: ["v*"]
 
 # Required repository secrets:
-#   REGISTRY            registry hostname, e.g. registry.librete.ch
-#   REGISTRY_USER       robot account
-#   REGISTRY_PASS       robot token
-#   DEPLOY_HOST         deployment SSH target, e.g. root@librenot.es
-#   DEPLOY_KEY          private SSH key (PEM, no passphrase)
-#   DEPLOY_PATH         remote directory containing the compose stack
-#   HEALTH_URL          public URL to verify post-deploy, e.g.
-#                       https://librenot.es/healthz
+#   REGISTRY            registry hostname (git.librete.ch)
+#   REGISTRY_USER       robot account or PAT username (libretech-bot)
+#   REGISTRY_PASS       PAT with write:package
+#   DEPLOY_HOST         SSH target, e.g. root@cloud.librete.ch
+#   DEPLOY_KEY          passphrase-less private key (PEM)
+#   DEPLOY_PATH         remote stack dir (/srv/librenotes)
+#   HEALTH_URL          https://ln.cloud.librete.ch/healthz
 #
-# Tag pushes deploy the tag (vX.Y.Z); main-branch pushes deploy
-# the rolling :main image. Set image to immutable tag so rollback
-# is just `docker compose -f ... up -d` with the previous tag.
+# Required repository variable:
+#   DEPLOY_ENABLED      set to "true" to enable the workflow
+#
+# Image: ${REGISTRY}/public/librenotes
+#   main pushes  → :main + :<sha7>
+#   tag pushes   → :<tag> + :latest
+#
+# The host's /srv/librenotes/.env pins LIBRENOTES_IMAGE once
+# (e.g. =git.librete.ch/public/librenotes:main). Main pushes
+# update :main rolling so a `compose pull` picks up the new image
+# without rewriting any file. Tag pin / rollback is a manual edit
+# of LIBRENOTES_IMAGE in .env followed by `compose pull && up -d`.
 
 jobs:
-  build:
+  deploy:
     runs-on: ubuntu-latest
-    timeout-minutes: 15
+    # Custom Gitea runner image: Ubuntu 24.04 + docker CLI + node + git
+    # + perl + ssh, runner user pre-joined to docker gid 998 so the
+    # auto-mounted /var/run/docker.sock is writable without --user root.
+    container:
+      image: git.librete.ch/libretech/runner-image:v1
+    timeout-minutes: 20
     if: ${{ vars.DEPLOY_ENABLED == 'true' }}
     steps:
       - uses: actions/checkout@v4
 
       - uses: docker/setup-buildx-action@v3
 
-      - name: Log in to registry
-        uses: docker/login-action@v3
+      - uses: docker/login-action@v3
         with:
           registry: ${{ secrets.REGISTRY }}
           username: ${{ secrets.REGISTRY_USER }}
           password: ${{ secrets.REGISTRY_PASS }}
 
-      - name: Compute tags
-        id: tags
-        run: |
-          BASE="${{ secrets.REGISTRY }}/librenotes"
-          if [[ "${GITHUB_REF}" == refs/tags/* ]]; then
-            TAG="${GITHUB_REF##refs/tags/}"
-            echo "tags=${BASE}:${TAG},${BASE}:latest" >> "$GITHUB_OUTPUT"
-            echo "version=${TAG}" >> "$GITHUB_OUTPUT"
-          else
-            echo "tags=${BASE}:main,${BASE}:${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT"
-            echo "version=${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT"
-          fi
+      - id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ secrets.REGISTRY }}/public/librenotes
+          tags: |
+            type=ref,event=branch
+            type=ref,event=tag
+            type=sha,format=short
+            type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/') }}
 
       - uses: docker/build-push-action@v6
         with:
           context: .
           push: true
-          tags: ${{ steps.tags.outputs.tags }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
           build-args: |
-            VERSION=${{ steps.tags.outputs.version }}
+            VERSION=${{ steps.meta.outputs.version }}
             BUILDTIME=${{ github.event.head_commit.timestamp }}
 
-  deploy:
-    runs-on: ubuntu-latest
-    needs: build
-    timeout-minutes: 10
-    if: ${{ vars.DEPLOY_ENABLED == 'true' }}
-    steps:
-      - name: Configure SSH
-        run: |
-          mkdir -p ~/.ssh
-          echo "${{ secrets.DEPLOY_KEY }}" > ~/.ssh/id_deploy
-          chmod 600 ~/.ssh/id_deploy
-          ssh-keyscan -H "${{ secrets.DEPLOY_HOST#*@ }}" >> ~/.ssh/known_hosts || true
-
-      - name: Pull and restart on deploy host
+      - name: Deploy to host
         env:
           DEPLOY_HOST: ${{ secrets.DEPLOY_HOST }}
+          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
           DEPLOY_PATH: ${{ secrets.DEPLOY_PATH }}
-        run: |
-          ssh -i ~/.ssh/id_deploy "$DEPLOY_HOST" \
-            "cd $DEPLOY_PATH && \
-             docker compose -f docker-compose.yml -f docker-compose.prod.yml pull && \
-             docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --remove-orphans"
-
-      - name: Verify health
-        env:
           HEALTH_URL: ${{ secrets.HEALTH_URL }}
         run: |
-          # Give the new container ~30s to come up, then poll for
-          # a 200 from /healthz. Failure aborts the workflow which
-          # is the alert.
+          mkdir -p ~/.ssh && chmod 700 ~/.ssh
+          printf '%s\n' "$DEPLOY_KEY" > ~/.ssh/id_deploy
+          chmod 600 ~/.ssh/id_deploy
+
+          ssh -i ~/.ssh/id_deploy \
+              -o StrictHostKeyChecking=accept-new \
+              "$DEPLOY_HOST" \
+              "set -e
+               cd '$DEPLOY_PATH'
+               git pull --ff-only
+               docker compose -f compose.yaml -f compose.netcup.yaml pull
+               docker compose -f compose.yaml -f compose.netcup.yaml up -d --remove-orphans"
+
+          # Wait up to 60s for /healthz to return 200.
           for i in $(seq 1 12); do
-            if curl -fsS "$HEALTH_URL" >/dev/null; then
-              echo "deploy verified"
-              exit 0
-            fi
+            curl -fsS "$HEALTH_URL" >/dev/null && exit 0
             sleep 5
           done
-          echo "deploy verification failed"
-          exit 1
+          echo "deploy health check failed"; exit 1

CLAUDE.md

@@ -18,7 +18,7 @@ Cloud-native multi-tenant notes application built on Notesium (MIT).
 
 ## Wave pipelines
 
-- `gt-issue-*` pipelines use `tea` CLI with `--login librete`
+- `gt-issue-*` pipelines use `tea` CLI with `--login libretech`
 - `gh-issue-*` pipelines use `gh` CLI
 - Personas must be registered in `wave.yaml` under `personas:` key — files alone aren't enough
 - `wave.yaml` is gitignored (local config)
@@ -27,6 +27,6 @@ Cloud-native multi-tenant notes application built on Notesium (MIT).
 ## Gitea
 
 - Instance: https://git.librete.ch
-- Auth: `tea` CLI, login name `librete`
+- Auth: `tea` CLI, login name `libretech` (matches the Gitea username)
 - API: https://git.librete.ch/api/v1
 - Issues: https://git.librete.ch/public/librenotes/issues

compose.netcup.yaml

@@ -1,15 +1,19 @@
 # compose.netcup.yaml — overlay for the netcup VPS.
 #
 # Use:
-#   docker compose -f docker-compose.yml -f compose.netcup.yaml up -d --build
+#   docker compose -f compose.yaml -f compose.netcup.yaml pull
+#   docker compose -f compose.yaml -f compose.netcup.yaml up -d
 #
-# Differences from base docker-compose.yml:
+# Differences from base compose.yaml:
+#   - Pulls a published image (no build context on the host)
 #   - No host port binding (caddy edge handles ingress)
 #   - Joins external `edge` network so caddy reaches it as `librenotes:8080`
-#   - Pulls config from .env (LIBRENOTES_BASE_URL, JWT_SECRET, SMTP_*)
+#   - Pulls config from .env (LIBRENOTES_BASE_URL, JWT_SECRET, SMTP_*, IMAGE)
 #   - Uses bind-mounted /data + /var/lib/librenotes so backups can rsync host paths
 #
 # Inputs (env or .env file on netcup):
+#   LIBRENOTES_IMAGE        e.g. git.librete.ch/public/librenotes:main
+#                           or pinned tag git.librete.ch/public/librenotes:v0.1.0
 #   LIBRENOTES_BASE_URL     https://ln.cloud.librete.ch
 #   LIBRENOTES_JWT_SECRET   `openssl rand -base64 48`
 #   LIBRENOTES_SMTP_HOST    SMTP relay host
@@ -17,14 +21,15 @@
 #   LIBRENOTES_SMTP_USER    SMTP user
 #   LIBRENOTES_SMTP_PASS    SMTP password
 #   LIBRENOTES_SMTP_FROM    no-reply@librete.ch (envelope sender)
+#
+# Rollback: edit LIBRENOTES_IMAGE in /srv/librenotes/.env to a prior
+# tag, then `docker compose ... pull && docker compose ... up -d`.
 
 services:
   librenotes:
-    build:
-      context: .
-      args:
-        VERSION: netcup
-    image: librenotes:netcup
+    build: !reset null
+    image: ${LIBRENOTES_IMAGE}
+    pull_policy: always
     restart: always
     ports: !reset []
     environment:

compose.yaml

@@ -1,4 +1,4 @@
-# docker-compose.yml — local development.
+# compose.yaml — local development.
 #
 # Brings up librenotes on http://localhost:8080 with the magic-link
 # mailer logging links to stdout (no SMTP needed). Data lives in

docker-compose.prod.yml

@@ -1,43 +0,0 @@
-# docker-compose.prod.yml — production overrides.
-#
-# Use:
-#   docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
-#
-# Inputs (env or .env file):
-#   LIBRENOTES_IMAGE        registry image, e.g. registry.librete.ch/librenotes:1.2.3
-#   LIBRENOTES_BASE_URL     public origin, e.g. https://librenot.es
-#   LIBRENOTES_JWT_SECRET   secrets manager value, NOT committed
-#   LIBRENOTES_SMTP_HOST    real SMTP host
-#   LIBRENOTES_SMTP_PORT    submission port (587 default)
-#   LIBRENOTES_SMTP_USER    SMTP credential
-#   LIBRENOTES_SMTP_PASS    SMTP credential
-#   LIBRENOTES_SMTP_FROM    envelope sender (e.g. no-reply@librenot.es)
-services:
-  librenotes:
-    image: ${LIBRENOTES_IMAGE}
-    build: !reset null
-    environment:
-      LIBRENOTES_BASE_URL: ${LIBRENOTES_BASE_URL}
-      LIBRENOTES_JWT_SECRET: ${LIBRENOTES_JWT_SECRET}
-      LIBRENOTES_SMTP_HOST: ${LIBRENOTES_SMTP_HOST}
-      LIBRENOTES_SMTP_PORT: ${LIBRENOTES_SMTP_PORT:-587}
-      LIBRENOTES_SMTP_USER: ${LIBRENOTES_SMTP_USER}
-      LIBRENOTES_SMTP_PASS: ${LIBRENOTES_SMTP_PASS}
-      LIBRENOTES_SMTP_FROM: ${LIBRENOTES_SMTP_FROM}
-    healthcheck:
-      test: ["CMD", "/librenotes", "healthcheck"]
-      interval: 30s
-      timeout: 5s
-      retries: 3
-      start_period: 10s
-    deploy:
-      resources:
-        limits:
-          memory: 256M
-        reservations:
-          memory: 64M
-    logging:
-      driver: json-file
-      options:
-        max-size: "10m"
-        max-file: "5"

docs/operations.md

@@ -21,42 +21,66 @@ The workflow expects these secrets and variables on the repo:
 
 | Name | Type | Purpose |
 | ---- | ---- | ------- |
-| `REGISTRY` | secret | hostname of the OCI registry |
-| `REGISTRY_USER` | secret | robot account |
-| `REGISTRY_PASS` | secret | robot token |
-| `DEPLOY_HOST` | secret | `user@host` SSH target |
-| `DEPLOY_KEY` | secret | passphrase-less private key |
-| `DEPLOY_PATH` | secret | absolute path on host with `docker-compose.*.yml` |
-| `HEALTH_URL` | secret | e.g. `https://librenot.es/healthz` |
+| `REGISTRY` | secret | registry hostname, e.g. `git.librete.ch` |
+| `REGISTRY_USER` | secret | robot account or PAT username with `package:write` |
+| `REGISTRY_PASS` | secret | robot/PAT token |
+| `DEPLOY_HOST` | secret | `user@host` SSH target, e.g. `root@netcup` |
+| `DEPLOY_KEY` | secret | passphrase-less private key (PEM) |
+| `DEPLOY_PATH` | secret | absolute path on host with the compose stack, e.g. `/srv/librenotes` |
+| `HEALTH_URL` | secret | e.g. `https://ln.cloud.librete.ch/healthz` |
 | `DEPLOY_ENABLED` | variable | `true` to enable the workflow |
 
+The image is pushed to `${REGISTRY}/public/librenotes`; main pushes
+publish `:main` and `:<sha7>`, tag pushes publish `:vX.Y.Z` and
+`:latest`.
+
 ### Production compose stack
 
-On the deployment host, place `docker-compose.yml` and
-`docker-compose.prod.yml` from this repo at `$DEPLOY_PATH`,
-together with an `.env` file containing the runtime configuration
-(JWT secret, SMTP credentials, public base URL, image tag).
+On the deployment host, place `compose.yaml` and
+`compose.netcup.yaml` from this repo at `$DEPLOY_PATH`, together
+with an `.env` file containing `LIBRENOTES_IMAGE` plus the runtime
+configuration (JWT secret, SMTP credentials, public base URL).
+See `.env.netcup.example` for the full key list.
 
 Bring it up with:
 
 ```sh
-docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+docker compose -f compose.yaml -f compose.netcup.yaml pull
+docker compose -f compose.yaml -f compose.netcup.yaml up -d
 ```
 
 ### Rollback
 
-Image tags are immutable per commit / version. To roll back, set
-`LIBRENOTES_IMAGE` to the previous tag in `.env` and run the same
-`up -d` command. The deployment workflow does not auto-rollback
-on health-check failure — failed health alerts the operator via
-the workflow itself, who can then redeploy the prior tag manually.
+Tag pushes publish immutable tags (`:vX.Y.Z`). To pin or roll back,
+edit `LIBRENOTES_IMAGE` in `/srv/librenotes/.env` and re-run pull +
+up. The deployment workflow itself never rewrites the file — failed
+health checks abort the workflow and the operator redeploys
+manually.
 
 ```sh
-# Example: roll back to v0.1.2
-sed -i 's/^LIBRENOTES_IMAGE=.*/LIBRENOTES_IMAGE=registry.librete.ch\/librenotes:v0.1.2/' .env
-docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+# Example: roll back to v0.1.0
+ssh netcup
+cd /srv/librenotes
+perl -i -pe 's|^LIBRENOTES_IMAGE=.*|LIBRENOTES_IMAGE=git.librete.ch/public/librenotes:v0.1.0|' .env
+docker compose -f compose.yaml -f compose.netcup.yaml pull
+docker compose -f compose.yaml -f compose.netcup.yaml up -d
 ```
 
+### Gitea Actions runner
+
+Workflows run on the netcup `act_runner` (see `runner/` stack in
+the netcup umbrella). Both `ci.yml` and `deploy.yml` declare
+`container: image: git.librete.ch/libretech/runner-image:v1` —
+a bespoke Ubuntu 24.04 image (built and signed by us, hosted on
+the same Gitea instance) that bundles `git`, `make`, `node`,
+`perl`, `ssh`, and a docker CLI. The image's `runner` user is
+pre-joined to `docker` group gid 998 so the auto-mounted
+`/var/run/docker.sock` is writable without `--user root`.
+
+The runner config (`runner/config.yaml`) whitelists
+`/var/run/docker.sock` under `valid_volumes` to allow the
+auto-mount.
+
 ## Backups
 
 `scripts/backup.sh` is a self-contained backup driver suitable for

docs/self-hosting.md

@@ -23,10 +23,16 @@ Docker Compose. For day-2 ops (deploys, backups) see
 ```sh
 git clone https://git.librete.ch/public/librenotes
 cd librenotes
-cp .env.example .env  # edit values, see below
-docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+cp .env.netcup.example .env  # edit values, see below
+docker compose -f compose.yaml -f compose.netcup.yaml pull
+docker compose -f compose.yaml -f compose.netcup.yaml up -d
 ```
 
+The `compose.netcup.yaml` overlay is the production-style overlay
+shipped in this repo; it pulls a published image, drops host port
+binding (assumes a fronting reverse proxy), and joins an external
+`edge` docker network. Adapt to your topology if needed.
+
 Visit `https://your-domain/` and sign in.
 
 ## Environment configuration
@@ -45,7 +51,7 @@ Place them in an `.env` file next to the Compose stack.
 | `LIBRENOTES_SMTP_FROM` | yes | Envelope sender, e.g. `no-reply@notes.example.com`. |
 | `LIBRENOTES_DATA_DIR` | no | Default `/data` inside the container. |
 | `LIBRENOTES_DB` | no | Default `/var/lib/librenotes/librenotes.db`. |
-| `LIBRENOTES_IMAGE` | yes (prod) | Image tag to pull, e.g. `registry.librete.ch/librenotes:v0.1.0`. |
+| `LIBRENOTES_IMAGE` | yes (prod) | Image tag to pull, e.g. `git.librete.ch/public/librenotes:v0.1.0`. |
 
 Generate a JWT secret:
 
@@ -109,8 +115,8 @@ to use `curl`/`wget`).
 Pull the new image and restart:
 
 ```sh
-docker compose -f docker-compose.yml -f docker-compose.prod.yml pull
-docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+docker compose -f compose.yaml -f compose.netcup.yaml pull
+docker compose -f compose.yaml -f compose.netcup.yaml up -d
 ```
 
 To pin a specific version, set `LIBRENOTES_IMAGE` to that tag in