.env.netcup.example

@@ -1,5 +1,10 @@
 # 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. Main pushes update :main; tag pushes pin to immutable
+# tags such as :v0.1.0. The deploy workflow rewrites this line on tag
+# pushes; rollback is `perl -i -pe 's|...|=...:vX.Y.Z|' .env && 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
+    # Pin image: needs make (not in node:20-bookworm). runner-latest
+    # bundles make, git, curl + node for setup-go.
+    container:
+      image: catthehacker/ubuntu:runner-latest
     timeout-minutes: 5
     steps:
       - name: Checkout

.gitea/workflows/deploy.yml

@@ -6,24 +6,38 @@ 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
+#   REGISTRY            registry hostname, e.g. git.librete.ch
+#   REGISTRY_USER       robot account or PAT username
+#   REGISTRY_PASS       robot/PAT token with package:write
+#   DEPLOY_HOST         deployment SSH target, e.g. root@netcup
 #   DEPLOY_KEY          private SSH key (PEM, no passphrase)
-#   DEPLOY_PATH         remote directory containing the compose stack
+#   DEPLOY_PATH         remote stack directory, e.g. /srv/librenotes
 #   HEALTH_URL          public URL to verify post-deploy, e.g.
-#                       https://librenot.es/healthz
+#                       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 path: ${REGISTRY}/public/librenotes (matches Gitea owner/repo).
+# Main pushes publish :main and :<sha7>. Tag pushes publish :<tag> and
+# :latest, then pin LIBRENOTES_IMAGE on the host to the immutable tag
+# so rollback is just `perl -i -pe 's|^LIBRENOTES_IMAGE=.*|...=...:vX.Y.Z|' .env`
+# followed by `docker compose ... up -d`.
 
 jobs:
   build:
     runs-on: ubuntu-latest
+    # Gitea Actions: pin image so docker CLI is present and mount the
+    # host docker socket so build-push-action can push to the registry.
+    # The runner declares /var/run/docker.sock in valid_volumes.
+    container:
+      image: catthehacker/ubuntu:runner-latest
+      volumes:
+        - /var/run/docker.sock:/var/run/docker.sock
     timeout-minutes: 15
     if: ${{ vars.DEPLOY_ENABLED == 'true' }}
+    outputs:
+      image_ref: ${{ steps.tags.outputs.image_ref }}
     steps:
       - uses: actions/checkout@v4
 
@@ -39,14 +53,17 @@ jobs:
       - name: Compute tags
         id: tags
         run: |
-          BASE="${{ secrets.REGISTRY }}/librenotes"
+          BASE="${{ secrets.REGISTRY }}/public/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"
+            echo "image_ref=${BASE}:${TAG}" >> "$GITHUB_OUTPUT"
           else
-            echo "tags=${BASE}:main,${BASE}:${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT"
-            echo "version=${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT"
+            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
@@ -60,34 +77,48 @@ jobs:
 
   deploy:
     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 }}
         run: |
           mkdir -p ~/.ssh
-          echo "${{ secrets.DEPLOY_KEY }}" > ~/.ssh/id_deploy
+          printf '%s\n' "$DEPLOY_KEY" > ~/.ssh/id_deploy
           chmod 600 ~/.ssh/id_deploy
-          ssh-keyscan -H "${{ secrets.DEPLOY_HOST#*@ }}" >> ~/.ssh/known_hosts || true
+          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: |
-          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"
+          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"
 
       - 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.
+          # 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
               echo "deploy verified"

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.prod.yaml

@@ -1,10 +1,12 @@
-# docker-compose.prod.yml — production overrides.
+# compose.prod.yaml — production overrides (generic, non-netcup).
 #
 # Use:
-#   docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+#   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. registry.librete.ch/librenotes:1.2.3
+#   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

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

docs/operations.md

@@ -21,26 +21,32 @@ 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
@@ -52,11 +58,27 @@ on health-check failure — failed health alerts the operator via
 the workflow itself, who can then redeploy the prior tag 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
+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 jobs declare `container: catthehacker/ubuntu:runner-latest`
+because:
+
+- The default runner label image (`node:20-bookworm`) lacks `make`
+  and `docker`, both required by the workflows.
+- The `runner-latest` image bundles `make`, `git`, `curl`, `ssh`,
+  `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
 
 `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