ci(deploy): switch to libretech/runner-image:v1, consolidate workflow (#43)

.env.netcup.example

@@ -1,9 +1,11 @@
 # Server-side .env for netcup deploy. Copy to /srv/librenotes/.env on the host.
 # Used by: docker compose -f compose.yaml -f compose.netcup.yaml up -d
 
-# Image to pull. Main pushes update :main; tag pushes pin to immutable
+# Image to pull. The default `:main` rolls forward — main pushes
-# tags such as :v0.1.0. The deploy workflow rewrites this line on tag
+# rebuild and push the same tag, so `compose pull` picks up the new
-# pushes; rollback is `perl -i -pe 's|...|=...:vX.Y.Z|' .env && up -d`.
+# 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)

.gitea/workflows/ci.yml

@@ -9,10 +9,10 @@ on:
 jobs:
   ci:
     runs-on: ubuntu-latest
-    # Pin image: needs make (not in node:20-bookworm). runner-latest
+    # Bespoke runner image (Ubuntu 24.04 + make + git + node + go via
-    # bundles make, git, curl + node for setup-go.
+    # actions/setup-go). See git.librete.ch/libretech/runner-image.
     container:
-      image: catthehacker/ubuntu:runner-latest
+      image: git.librete.ch/libretech/runner-image:v1
     timeout-minutes: 5
     steps:
       - name: Checkout

.gitea/workflows/deploy.yml

@@ -6,124 +6,91 @@ on:
     tags: ["v*"]
 
 # Required repository secrets:
-#   REGISTRY            registry hostname, e.g. git.librete.ch
+#   REGISTRY            registry hostname (git.librete.ch)
-#   REGISTRY_USER       robot account or PAT username
+#   REGISTRY_USER       robot account or PAT username (libretech-bot)
-#   REGISTRY_PASS       robot/PAT token with package:write
+#   REGISTRY_PASS       PAT with write:package
-#   DEPLOY_HOST         deployment SSH target, e.g. root@netcup
+#   DEPLOY_HOST         SSH target, e.g. root@cloud.librete.ch
-#   DEPLOY_KEY          private SSH key (PEM, no passphrase)
+#   DEPLOY_KEY          passphrase-less private key (PEM)
-#   DEPLOY_PATH         remote stack directory, e.g. /srv/librenotes
+#   DEPLOY_PATH         remote stack dir (/srv/librenotes)
-#   HEALTH_URL          public URL to verify post-deploy, e.g.
+#   HEALTH_URL          https://ln.cloud.librete.ch/healthz
-#                       https://ln.cloud.librete.ch/healthz
 #
 # Required repository variable:
 #   DEPLOY_ENABLED      set to "true" to enable the workflow
 #
-# Image path: ${REGISTRY}/public/librenotes (matches Gitea owner/repo).
+# Image: ${REGISTRY}/public/librenotes
-# Main pushes publish :main and :<sha7>. Tag pushes publish :<tag> and
+#   main pushes  → :main + :<sha7>
-# :latest, then pin LIBRENOTES_IMAGE on the host to the immutable tag
+#   tag pushes   → :<tag> + :latest
-# so rollback is just `perl -i -pe 's|^LIBRENOTES_IMAGE=.*|...=...:vX.Y.Z|' .env`
+#
-# followed by `docker compose ... up -d`.
+# 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
-    # Gitea Actions: pin image so docker CLI is present. The runner
+    # Custom Gitea runner image: Ubuntu 24.04 + docker CLI + node + git
-    # already bind-mounts /var/run/docker.sock into job containers
+    # + perl + ssh, runner user pre-joined to docker gid 998 so the
-    # automatically (because it has the socket mounted itself); adding
+    # auto-mounted /var/run/docker.sock is writable without --user root.
-    # `volumes:` here again triggers a duplicate-mount-point error.
     container:
-      image: catthehacker/ubuntu:runner-latest
+      image: git.librete.ch/libretech/runner-image:v1
-    timeout-minutes: 15
+    timeout-minutes: 20
     if: ${{ vars.DEPLOY_ENABLED == 'true' }}
-    outputs:
-      image_ref: ${{ steps.tags.outputs.image_ref }}
     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: meta
-        id: tags
+        uses: docker/metadata-action@v5
-        run: |
+        with:
-          BASE="${{ secrets.REGISTRY }}/public/librenotes"
+          images: ${{ secrets.REGISTRY }}/public/librenotes
-          if [[ "${GITHUB_REF}" == refs/tags/* ]]; then
+          tags: |
-            TAG="${GITHUB_REF##refs/tags/}"
+            type=ref,event=branch
-            echo "tags=${BASE}:${TAG},${BASE}:latest" >> "$GITHUB_OUTPUT"
+            type=ref,event=tag
-            echo "version=${TAG}" >> "$GITHUB_OUTPUT"
+            type=sha,format=short
-            echo "image_ref=${BASE}:${TAG}" >> "$GITHUB_OUTPUT"
+            type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/') }}
-          else
-            SHA7="${GITHUB_SHA::7}"
-            echo "tags=${BASE}:main,${BASE}:${SHA7}" >> "$GITHUB_OUTPUT"
-            echo "version=${SHA7}" >> "$GITHUB_OUTPUT"
-            echo "image_ref=${BASE}:main" >> "$GITHUB_OUTPUT"
-          fi
 
       - 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:
+      - name: Deploy to host
-    runs-on: ubuntu-latest
-    # Same image as build — bundles ssh, perl, curl. No docker needed.
-    container:
-      image: catthehacker/ubuntu:runner-latest
-    needs: build
-    timeout-minutes: 10
-    if: ${{ vars.DEPLOY_ENABLED == 'true' }}
-    steps:
-      - name: Configure SSH
         env:
           DEPLOY_HOST: ${{ secrets.DEPLOY_HOST }}
           DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
+          DEPLOY_PATH: ${{ secrets.DEPLOY_PATH }}
+          HEALTH_URL: ${{ secrets.HEALTH_URL }}
         run: |
-          mkdir -p ~/.ssh
+          mkdir -p ~/.ssh && chmod 700 ~/.ssh
           printf '%s\n' "$DEPLOY_KEY" > ~/.ssh/id_deploy
           chmod 600 ~/.ssh/id_deploy
-          ssh-keyscan -H "${DEPLOY_HOST#*@}" >> ~/.ssh/known_hosts 2>/dev/null || true
 
-      - name: Pull and restart on deploy host
-        env:
-          DEPLOY_HOST: ${{ secrets.DEPLOY_HOST }}
-          DEPLOY_PATH: ${{ secrets.DEPLOY_PATH }}
-          IMAGE_REF: ${{ needs.build.outputs.image_ref }}
-        run: |
-          REMOTE_CMD='cd "$DEPLOY_PATH" || exit 1
-          git pull --ff-only
-          # Always pin LIBRENOTES_IMAGE so first deploy works without manual
-          # .env priming and so rollback only ever needs an .env edit.
-          perl -i -pe "s|^LIBRENOTES_IMAGE=.*|LIBRENOTES_IMAGE=$IMAGE_REF|" .env
-          grep -q "^LIBRENOTES_IMAGE=" .env || echo "LIBRENOTES_IMAGE=$IMAGE_REF" >> .env
-          docker compose -f compose.yaml -f compose.netcup.yaml pull
-          docker compose -f compose.yaml -f compose.netcup.yaml up -d --remove-orphans'
           ssh -i ~/.ssh/id_deploy \
               -o StrictHostKeyChecking=accept-new \
               "$DEPLOY_HOST" \
-              "DEPLOY_PATH='$DEPLOY_PATH' IMAGE_REF='$IMAGE_REF' bash -s" <<< "$REMOTE_CMD"
+              "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"
 
-      - name: Verify health
+          # Wait up to 60s for /healthz to return 200.
-        env:
-          HEALTH_URL: ${{ secrets.HEALTH_URL }}
-        run: |
-          # Give the new container ~60s to come up, then poll for
-          # 200 from /healthz. Failure aborts the workflow.
           for i in $(seq 1 12); do
-            if curl -fsS "$HEALTH_URL" >/dev/null; then
+            curl -fsS "$HEALTH_URL" >/dev/null && exit 0
-              echo "deploy verified"
-              exit 0
-            fi
             sleep 5
           done
-          echo "deploy verification failed"
+          echo "deploy health check failed"; exit 1
-          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.prod.yaml

@@ -1,45 +0,0 @@
-# compose.prod.yaml — production overrides (generic, non-netcup).
-#
-# Use:
-#   docker compose -f compose.yaml -f compose.prod.yaml up -d
-#
-# For the netcup deployment, use `compose.netcup.yaml` instead.
-#
-# Inputs (env or .env file):
-#   LIBRENOTES_IMAGE        registry image, e.g. git.librete.ch/public/librenotes:v0.1.0
-#   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

@@ -51,14 +51,16 @@ docker compose -f compose.yaml -f compose.netcup.yaml up -d
 
 ### Rollback
 
-Image tags are immutable per commit / version. To roll back, set
+Tag pushes publish immutable tags (`:vX.Y.Z`). To pin or roll back,
-`LIBRENOTES_IMAGE` to the previous tag in `.env` and run the same
+edit `LIBRENOTES_IMAGE` in `/srv/librenotes/.env` and re-run pull +
-`up -d` command. The deployment workflow does not auto-rollback
+up. The deployment workflow itself never rewrites the file — failed
-on health-check failure — failed health alerts the operator via
+health checks abort the workflow and the operator redeploys
-the workflow itself, who can then redeploy the prior tag manually.
+manually.
 
 ```sh
 # 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
@@ -67,17 +69,17 @@ 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 jobs declare `container: catthehacker/ubuntu:runner-latest`
+the netcup umbrella). Both `ci.yml` and `deploy.yml` declare
-because:
+`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 default runner label image (`node:20-bookworm`) lacks `make`
+The runner config (`runner/config.yaml`) whitelists
-  and `docker`, both required by the workflows.
+`/var/run/docker.sock` under `valid_volumes` to allow the
-- The `runner-latest` image bundles `make`, `git`, `curl`, `ssh`,
+auto-mount.
-  `node`, plus a docker CLI.
-
-The runner config (`runner/config.yaml`) declares
-`/var/run/docker.sock` as a `valid_volume` so the build job can
-mount the host socket and push images via `docker/build-push-action`.
 
 ## Backups