Ignore runtime data and state of the stopped stack (#57)

Co-authored-by: Michael Czechowski <mail@librete.ch>

.gitea/workflows/ci.yml

@@ -10,9 +10,9 @@ 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.
+    # actions/setup-go). See git.librete.ch/public/runner-image.
     container:
-      image: git.librete.ch/libretech/runner-image:v1
+      image: git.librete.ch/public/runner-image:v0.2.0@sha256:f60c587d3c0b0aac04a572db5349e27672bf76baec2ce547a3dcc28cebcf1b7e
     timeout-minutes: 5
     steps:
       - name: Checkout

.gitea/workflows/deploy.yml

@@ -34,7 +34,7 @@ jobs:
     # + 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
+      image: git.librete.ch/public/runner-image:v0.2.0@sha256:f60c587d3c0b0aac04a572db5349e27672bf76baec2ce547a3dcc28cebcf1b7e
     timeout-minutes: 20
     if: ${{ vars.DEPLOY_ENABLED == 'true' }}
     steps:

.gitignore

@@ -15,3 +15,10 @@ wave.yaml
 /dist/
 *.test
 *.out
+
+# Agent scratch
+/.agents/
+
+# runtime data and state of the stopped stack
+/data/
+/state/

AGENTS.md

@@ -0,0 +1 @@
+See CLAUDE.md for project guidelines.

CLAUDE.md

@@ -5,7 +5,7 @@ Cloud-native multi-tenant notes application built on Notesium (MIT).
 ## Project
 
 - Repo: https://git.librete.ch/public/librenotes
-- Remote: `https://git.librete.ch/public/librenotes.git`
+- Remote: `ssh://git.librete.ch:41240/public/librenotes.git` (configure SSH user in `~/.ssh/config`)
 - Stack: Go backend (forked from Notesium), vanilla JS frontend
 - License: MIT (inherited from Notesium)
 

DEPLOY.md

@@ -0,0 +1,82 @@
+# Deploy runbook — librenotes
+
+Derived from [`netcup/DEPLOY-TEMPLATE.md`](https://git.librete.ch/libretech/netcup/src/branch/main/DEPLOY-TEMPLATE.md).
+Section ordering and headings stable across stacks.
+
+## 1. Target
+
+| Field | Value |
+|-------|-------|
+| Vhost | `ln.cloud.librete.ch` |
+| Server path | `/srv/librenotes/` |
+| Repo | `git.librete.ch/public/librenotes` |
+| Image source | `${LIBRENOTES_IMAGE}` from `git.librete.ch/public/librenotes` (registry image, no source build on remote) |
+| Cert | edge caddy via INWX DNS-01 |
+| Edge net container name | `librenotes` (matches `caddy/Caddyfile` reverse_proxy target on `:8080`) |
+
+## 2. Required env / secrets
+
+`/srv/librenotes/.env` (gitignored, mode 0600):
+
+| Variable | Notes |
+|----------|-------|
+| `LIBRENOTES_IMAGE` | published tag, e.g. `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`, `..._PORT`, `..._USER`, `..._PASS`, `..._FROM` | outbound mail (uberspace per `netcup/.env`) |
+
+## 3. First-time deploy
+
+```sh
+ssh netcup 'docker network ls | grep -q edge || docker network create edge'
+ssh netcup 'mkdir -p /srv && cd /srv && git clone ssh://tengo@git.librete.ch:41240/public/librenotes.git'
+scp librenotes/.env netcup:/srv/librenotes/.env
+ssh netcup 'chmod 600 /srv/librenotes/.env'
+ssh netcup 'cd /srv/librenotes && docker compose -f compose.yaml -f compose.netcup.yaml pull && docker compose -f compose.yaml -f compose.netcup.yaml up -d'
+```
+
+## 4. Update deploy
+
+```sh
+deploy librenotes
+# Bump LIBRENOTES_IMAGE in /srv/librenotes/.env then:
+ssh netcup 'cd /srv/librenotes && docker compose -f compose.yaml -f compose.netcup.yaml pull && docker compose -f compose.yaml -f compose.netcup.yaml up -d'
+```
+
+## 5. Smoke / health
+
+```sh
+ping ln.cloud.librete.ch
+cert ln.cloud.librete.ch
+svcs librenotes
+logs librenotes librenotes --tail=100
+```
+
+UI smoke: signup magic-link email arrives, login succeeds, note creation persists.
+
+## 6. Logs + troubleshooting
+
+| Symptom | First check |
+|---------|-------------|
+| 502 from edge | container off `edge` net or down |
+| SMTP failure | `LIBRENOTES_SMTP_*` correct; firewall to uberspace |
+| State loss | bind-mount `./state:/var/lib/librenotes` permissions |
+
+## 7. Rollback
+
+```sh
+# Edit LIBRENOTES_IMAGE to prior tag in /srv/librenotes/.env, then:
+ssh netcup 'cd /srv/librenotes && docker compose -f compose.yaml -f compose.netcup.yaml pull && docker compose -f compose.yaml -f compose.netcup.yaml up -d'
+```
+
+## 8. Stack-specific notes
+
+- **Bind mounts** `./data:/data` (notes payload) and `./state:/var/lib/librenotes` (DB/state) — back up both.
+- Multi-tenant by base URL — single image instance per tenant config.
+- Image is published from `public/librenotes` CI; never builds on remote.
+
+## 9. Issue tracking
+
+- Deploy issues: `git.librete.ch/public/librenotes/issues`
+- Cross-stack: `libretech/netcup`
+- After every deploy: append to `netcup/deployments.md`.

README.md

@@ -7,6 +7,8 @@ Cloud-native, multi-tenant notes application. A fork of
 authentication, per-user data isolation, sync, and PWA support so it can
 run as a hosted service at [librenot.es](https://librenot.es).
 
+> **Deploy / operate on netcup:** see [DEPLOY.md](DEPLOY.md) (canonical netcup runbook).
+
 ## Features
 
 - Markdown notes with bi-directional links (Zettelkasten / evergreen notes)

docs/operations.md

@@ -70,7 +70,7 @@ docker compose -f compose.yaml -f compose.netcup.yaml up -d
 
 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` —
+`container: image: git.librete.ch/public/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

flake.nix

@@ -48,6 +48,10 @@
             --bind "$HOME/.claude" "$HOME/.claude"
             --bind "$HOME/.claude.json" "$HOME/.claude.json"
 
+            # Writable: GPG keyring + agent socket (commit signing)
+            --bind "$HOME/.gnupg" "$HOME/.gnupg"
+            --bind-try "''${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/gnupg" "''${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/gnupg"
+
             --ro-bind "$HOME/.gitconfig" "$HOME/.gitconfig"
             --ro-bind "$HOME/.ssh" "$HOME/.ssh"
             --setenv GIT_SSH_COMMAND "ssh -F ~/.ssh/config"
@@ -61,6 +65,7 @@
             --setenv PATH "$PATH"
             --setenv TERM "''${TERM:-xterm}"
             --setenv SANDBOX_ACTIVE "1"
+            --setenv GPG_TTY "''${GPG_TTY:-}"
             --chdir "$PROJECT_DIR"
           )