diff --git a/.gitea/workflows/deploy.yml b/.gitea/workflows/deploy.yml new file mode 100644 index 0000000..6e07923 --- /dev/null +++ b/.gitea/workflows/deploy.yml @@ -0,0 +1,116 @@ +# Tests every push and pull request; deploys pushes to master to the Plesk server. +# Setup (secrets, variables, Plesk): docs/deployment.md. +# +# Deploy = build here, rsync the standalone bundle over SSH into the Node app's folder as the +# subscription's own system user, then restart Passenger. No host paths are mounted into the +# runner and no Docker socket is needed - the same pattern works for any Node app on Plesk. +name: Test and deploy + +on: + push: + branches: [master] + pull_request: + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + # Same major as Passenger on the server (26.13.0 as of 2026-11-08). + node-version-file: .nvmrc + - run: npm ci + - run: npm run lint + - run: npx tsc --noEmit + - run: npm test + # Proves the production build works, with the production values: NEXT_PUBLIC_* are inlined + # at build time, and lib/env.ts fails the build if one is missing. + - run: npm run build + env: + NEXT_PUBLIC_API_BASE_URL: ${{ vars.NEXT_PUBLIC_API_BASE_URL }} + NEXT_PUBLIC_ADMIN_APP_URL: ${{ vars.NEXT_PUBLIC_ADMIN_APP_URL }} + + deploy: + needs: test + if: github.event_name == 'push' && github.ref == 'refs/heads/master' + runs-on: ubuntu-latest + env: + DEPLOY_HOST: ${{ vars.DEPLOY_HOST }} + DEPLOY_PORT: ${{ vars.DEPLOY_PORT }} + DEPLOY_USER: ${{ vars.DEPLOY_USER }} + DEPLOY_PATH: ${{ vars.DEPLOY_PATH }} + # Absolute paths on purpose: rsync hands its -e string to ssh without a shell, and ssh + # resolves "~" from the passwd entry, not $HOME - so "~/.ssh/..." can point somewhere else + # than where the previous step wrote the key (found in a local dry run, 2026-11-08). + SSH_DIR: /tmp/deploy-ssh + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version-file: .nvmrc + - run: npm ci + - name: Build + run: npm run build + env: + NEXT_PUBLIC_API_BASE_URL: ${{ vars.NEXT_PUBLIC_API_BASE_URL }} + NEXT_PUBLIC_ADMIN_APP_URL: ${{ vars.NEXT_PUBLIC_ADMIN_APP_URL }} + + # Passenger wants a document root inside the app root; the app has no static files of its + # own there (server.js serves .next/static), so an empty public/ is enough. Created here so + # rsync --delete doesn't remove it on the server. + - name: Prepare bundle + run: mkdir -p .next/standalone/public + + - name: SSH setup + env: + DEPLOY_SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }} + DEPLOY_KNOWN_HOSTS: ${{ secrets.DEPLOY_KNOWN_HOSTS }} + run: | + test -n "$DEPLOY_HOST" && test -n "$DEPLOY_USER" && test -n "$DEPLOY_PATH" + if ! command -v rsync >/dev/null 2>&1 || ! command -v ssh >/dev/null 2>&1; then + apt-get update && apt-get install -y --no-install-recommends rsync openssh-client + fi + install -m 700 -d "$SSH_DIR" + printf '%s\n' "$DEPLOY_SSH_KEY" > "$SSH_DIR/key" + chmod 600 "$SSH_DIR/key" + # Pinned host key, never trust-on-first-use: a job that accepts any key would hand the + # bundle to whoever answers on that address. + printf '%s\n' "$DEPLOY_KNOWN_HOSTS" > "$SSH_DIR/known_hosts" + + - name: Upload + run: | + # Straight into the app folder (no release folders - decided 2026-11-08; a rollback is a + # redeploy of an older commit). That folder is the one Plesk created for the subdomain, + # so --delete leaves alone what isn't ours: tmp/ (Passenger's restart.txt) and + # .well-known/ (in case Plesk puts certificate challenges there). + rsync -az --delete --exclude '/tmp/' --exclude '/.well-known/' \ + -e "ssh -p ${DEPLOY_PORT:-22} -i $SSH_DIR/key -o UserKnownHostsFile=$SSH_DIR/known_hosts -o IdentitiesOnly=yes -o BatchMode=yes" \ + .next/standalone/ "$DEPLOY_USER@$DEPLOY_HOST:$DEPLOY_PATH/" + + - name: Restart + run: | + # Passenger restarts the app on its next request when tmp/restart.txt is touched. + ssh -p "${DEPLOY_PORT:-22}" -i "$SSH_DIR/key" -o "UserKnownHostsFile=$SSH_DIR/known_hosts" \ + -o IdentitiesOnly=yes -o BatchMode=yes "$DEPLOY_USER@$DEPLOY_HOST" \ + "mkdir -p '$DEPLOY_PATH/tmp' && touch '$DEPLOY_PATH/tmp/restart.txt'" + + # Optional until Plesk serves the Node app: set DEPLOY_SMOKE_URL then. Checks the page loads + # and references the build's static files (the classic standalone failure is missing CSS/JS). + - name: Smoke test + if: vars.DEPLOY_SMOKE_URL != '' + env: + DEPLOY_SMOKE_URL: ${{ vars.DEPLOY_SMOKE_URL }} + run: | + for _ in 1 2 3 4 5 6; do + if page="$(curl -fsS "$DEPLOY_SMOKE_URL")"; then break; fi + sleep 5 + done + echo "$page" | grep -q '/_next/static/' + asset="$(echo "$page" | grep -o '/_next/static/[^"]*\.css' | head -1)" + curl -fsS -o /dev/null "${DEPLOY_SMOKE_URL%/}$asset" + echo "OK: page and $asset served" + + - name: Remove key + if: always() + run: rm -f "$SSH_DIR/key" diff --git a/CLAUDE.md b/CLAUDE.md index d56f263..9fff938 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -25,7 +25,7 @@ npm test # Vitest, pure logic in lib/ (runs with TZ=America/New_York o - [docs/features.md](docs/features.md) - what the app does - [docs/gotchas.md](docs/gotchas.md) - read before assuming how the API, Next or Base UI behaves - [docs/api-wishlist.md](docs/api-wishlist.md) - API changes this app would like -- [docs/deployment.md](docs/deployment.md) - Plesk build/run, switchover, rollback +- [docs/deployment.md](docs/deployment.md) - Gitea Actions workflow (`.gitea/workflows/deploy.yml`), Plesk setup, switchover, rollback - [docs/rewrite-plan.md](docs/rewrite-plan.md) - the Angular → Next rewrite: decisions and progress log ## Architecture diff --git a/docs/deployment.md b/docs/deployment.md index f52fc66..e34abf5 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -1,69 +1,158 @@ # Deployment and switchover -How the Next.js app replaces the Angular build on `calendar.nachklang.art`. **The deploy itself is -done by a person** (never by Claude). Steps marked *unverified* could not be checked without access -to the Plesk server. +How the Next.js app runs on the Plesk server and gets there. Deploys run in **Gitea Actions** +(`.gitea/workflows/deploy.yml`), replacing the Jenkins job that copied the Angular build into the +webroot. Steps marked *unverified* could not be checked without access to the server; the first +real deploy settles them - record the outcome here. -## Order matters - -1. **API first**: merge and deploy the API branch `feature/calendar-ical-escaping-subscriptions` - (rebuild + restart; no new env vars - it uses the existing `API_BASE_URL` and - `*_CREDENTIAL` values). The old Angular app keeps working against it; the new app's "Abonnieren" - dialog needs it. -2. **Then the frontend.** - -## Build - -Node version: `.nvmrc` says 26, copied from the API repo - *unverified* that Plesk offers it; use -the version the API runs on. - -```bash -npm ci -NEXT_PUBLIC_API_BASE_URL=https://api.nachklang.art \ -NEXT_PUBLIC_ADMIN_APP_URL=https://admin.nachklang.art \ -npm run build +``` +push to master ──▶ Gitea ──▶ runner (Docker container on the Plesk server) + ├─ test job: npm ci, lint, tsc, test, build + └─ deploy job: build ─ rsync over SSH ─▶ nachklang@server: + └─ touch tmp/restart.txt +browser ──https──▶ Plesk (nginx + Passenger) ──▶ /server.js ``` -- Both values are **inlined at build time** - they must be set for `npm run build`, not just at - runtime. (Values from the Angular `environment.prod.ts`.) -- `npm run build` runs `postbuild`, which copies `.next/static` into `.next/standalone/.next/static`. - Without it the standalone server serves the pages without CSS and JS. -- The build fetches the public events from the API to prerender `/`. If it can't reach the API it - still succeeds. +Pull requests only run the test job. -## Run (Plesk Node.js / Passenger) +## Why SSH and not mounted paths -- Application startup file: `.next/standalone/server.js`. -- The server listens on `PORT` (and `HOSTNAME`). Whether Passenger sets `PORT` itself or needs it - configured is *unverified* - check how the feedback app is set up on the same server. -- Optional runtime env: `API_BASE_URL` (internal address for the landing page's server-side fetch). -- The subdomain changes from serving static files to a Node.js app. *Unverified* how Plesk handles - that switch for an existing domain (document root vs. application root). +Decided 2026-11-08. The Jenkins job wrote into the webroot through a path shared with the host. +The workflow instead connects as the subscription's own system user (`nachklang`) with a +dedicated deploy key: the job can only touch what that user can, files get the right owner +without `chown`, nothing on the host is mounted into the runner, and the same steps work for any +Node app on Plesk and keep working if the runner moves. No release folders: rsync writes straight +into the app root, and a rollback is a redeploy of an older commit. -Checked locally (2026-09-28): `PORT=4300 node .next/standalone/server.js` serves `/` with events, -CSS/JS (200), the favicon, and redirects `/admin` without a cookie to `/admin/login`. +## One-time setup -## Things that must already be true (unchanged from the Angular app) +### 1. SSH access for `nachklang` (Plesk) -The origin stays `https://calendar.nachklang.art`, so nothing should need changing - inferred from -the Angular app already using the same cookie auth: +*Websites & Domains → nachklang.art → Hosting & DNS → Hosting* (wording may differ by Plesk +version): set **Access to the server over SSH** from "Forbidden" to `/bin/bash (chrooted)`. +*Unverified* whether the chrooted environment includes `rsync`; if the first deploy fails with +"rsync: command not found" on the remote side, switch to `/bin/bash`. -- the API's CORS list contains `https://calendar.nachklang.art` (verified in `app.factory.ts`); -- the admin app's `NEXT_PUBLIC_ALLOWED_REDIRECT_ORIGINS` contains it (otherwise signing in lands on - the admin start page instead of coming back); -- the API's better-auth trusted origins contain it (otherwise sign-out fails). +### 2. Deploy key -## Smoke test after the switch +On any machine: -1. `/` loads styled, shows "Nächste Termine", and the Apple link opens a subscription. -2. `/admin` while signed out → admin login → back to `/admin` after signing in. -3. The list shows all calendars; an edit saves; "Abonnieren" lists links. -4. An account without calendar permission sees "Kein Zugriff" (no redirect loop). -5. "Abmelden" signs out and offers to sign in again. -6. On a phone: list, "+" button, bottom sheet. -7. An existing iCal subscription still updates (the feed URL is unchanged). +```bash +ssh-keygen -t ed25519 -N "" -f calendar-deploy -C "gitea-actions Calendar_Frontend" +``` + +- Append `calendar-deploy.pub` to `~/.ssh/authorized_keys` of `nachklang` on the server (Plesk's + SSH key management or the file manager; create `.ssh` with mode 700, the file with 600). +- The private key `calendar-deploy` goes into Gitea as a secret (below), then delete the local copy. + +### 3. Host key + +The job refuses any server whose host key it doesn't already know. Get the line it needs from +a machine that can reach the server, and compare its fingerprint with the server's own: + +```bash +ssh-keyscan -t ed25519 # → the secret DEPLOY_KNOWN_HOSTS +ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub # on the server: must match +``` + +`DEPLOY_HOST` must be reachable **from inside the runner's job containers**, which run on the +same server. The server's public hostname is the obvious choice; *unverified* that the server +can reach itself on its public address. If it can't, use the Docker bridge gateway instead (on +default Docker installs `172.17.0.1`) and scan that address for the known-hosts line. + +### 4. Gitea repository settings + +*Calendar_Frontend → Settings → Actions* (Actions must be enabled for the repo): + +| Kind | Name | Value | +|---|---|---| +| Secret | `DEPLOY_SSH_KEY` | private key from step 2 | +| Secret | `DEPLOY_KNOWN_HOSTS` | line(s) from step 3 | +| Variable | `NEXT_PUBLIC_API_BASE_URL` | `https://api.nachklang.art` | +| Variable | `NEXT_PUBLIC_ADMIN_APP_URL` | `https://admin.nachklang.art` | +| Variable | `DEPLOY_HOST` | from step 3 | +| Variable | `DEPLOY_USER` | `nachklang` | +| Variable | `DEPLOY_PATH` | `/var/www/vhosts/nachklang.art/calendar.nachklang.art` | +| Variable | `DEPLOY_PORT` | only if SSH isn't on 22 | +| Variable | `DEPLOY_SMOKE_URL` | `https://calendar.nachklang.art/` - **only after step 5** | + +The `NEXT_PUBLIC_*` values are inlined at build time; they are variables, not secrets, because +they end up in the JavaScript every visitor downloads anyway. + +`DEPLOY_PATH` is the folder Plesk created for the subdomain - the same one Jenkins copied the +Angular build into (decided 2026-11-08: don't move away from Plesk's own layout). rsync +`--delete` therefore skips what isn't the app's: `tmp/` (Passenger's `restart.txt`) and +`.well-known/` (in case Plesk keeps certificate challenges there - *unverified* whether it does). +The first deploy replaces the Angular files. + +### 5. Node.js app in Plesk + +*Websites & Domains → calendar.nachklang.art → Node.js*: + +- Node.js version: 26 (26.13.0 on the server as of 2026-11-08; the workflow builds with the major + from `.nvmrc`). +- Application root: `DEPLOY_PATH` (the subdomain's own folder). +- Document root: `DEPLOY_PATH/public` (an empty folder the workflow creates; Passenger wants one, + the app serves its own static files from `.next/static`). +- Application startup file: `server.js`. +- Application mode: production. +- **Don't** run "NPM install" there: the standalone bundle already contains its `node_modules`. +- Optional environment variable `API_BASE_URL` (server-side fetch of the landing page's events, + may be an internal address). + +Port: Passenger runs `server.js` itself and takes over the port it listens on (Passenger's +"reverse port binding" for Node apps) - *unverified* on this server; the Next server falls back +to port 3000 if Passenger doesn't intercept. + +## Switchover, in this order + +1. **API first.** Merge and deploy `feature/calendar-ical-escaping-subscriptions` (still the + existing API deploy; its Gitea workflow comes later). Backwards compatible with Angular. +2. **Disable the Jenkins job** for Calendar_Frontend. Otherwise it runs `ng build` on the next push + to master and fails - or worse, copies something into the old webroot. +3. **Steps 1-4 above** (SSH, key, host key, Gitea settings). +4. **Back up the Angular build**: download `calendar.nachklang.art/` as a ZIP in Plesk's file + manager. The first deploy replaces those files, and this backup is the quick way back. +5. **Merge** `feature/nextjs-rewrite` into master and watch the run under *Actions*. When the + deploy job has finished, the folder holds the Next app but Plesk still serves it as static + files - **the subdomain is down from here until step 6** (no `index.html` any more). +6. **Step 5 above, right away** - switch the subdomain to the Node app. This is the moment the new + app goes live; doing it right after the run keeps the gap to a few minutes. (Plesk might accept + the Node.js settings before the files exist, which would allow switching first - *unverified*.) +7. Set `DEPLOY_SMOKE_URL` and re-run the workflow (or push), so every later deploy checks that the + page and its CSS are served. +8. **Manual smoke test**: + 1. `/` loads styled, shows "Nächste Termine"; the Apple link opens a subscription. + 2. `/admin` signed out → admin login → back to `/admin`. + 3. List shows all calendars; an edit saves; "Abonnieren" lists links. + 4. An account without calendar permission sees "Kein Zugriff" (no redirect loop). + 5. "Abmelden" signs out and offers to sign in again. + 6. On a phone: list, "+" button, bottom sheet. + 7. An existing iCal subscription still updates (the feed URL is unchanged). + +Things that must already be true, unchanged from Angular because the origin stays the same +(inferred from the Angular app using the same cookie auth): the API's CORS list contains +`https://calendar.nachklang.art` (verified in `app.factory.ts`), and so do the admin app's +`NEXT_PUBLIC_ALLOWED_REDIRECT_ORIGINS` and the API's better-auth trusted origins. ## Rollback -Keep the last Angular build (`dist/nachklang-calendar`) for about a week and switch the subdomain -back to it if needed. The API change is backwards compatible with the Angular app, so it can stay. +- **Bad release:** revert the commit on master (or push the previous one); the workflow deploys it. +- **The Node app itself doesn't work:** switch Node.js off for `calendar.nachklang.art` in Plesk, set + the document root back to the subdomain folder, and restore the Angular backup from step 4 into + it (or rebuild Angular from commit `f822559`: `npm ci && npx ng build`). Disable the workflow + meanwhile, or the next push to master overwrites it again. Keep the backup about a week. + +## Checked locally (2026-11-08) + +- `actionlint` (in a container): no findings. +- The deploy job's shell steps, extracted from the workflow, run against a throwaway SSH server + (Alpine + openssh + rsync, user `nachklang`): bundle arrives owned by `nachklang`, `public/` and + `.next/static` present, `tmp/restart.txt` touched, key removed afterwards; a second deploy + removes stale files but keeps `tmp/`; a wrong host key aborts before anything is written. + Against a folder set up like today's subdomain folder (Angular files, `.well-known/`, `tmp/`): + the Angular files are replaced, `.well-known/` and `tmp/` stay. +- Earlier (2026-09-28): `PORT=4300 node .next/standalone/server.js` serves the styled page, CSS/JS + and the `/admin` redirect. + +Not checked: the workflow on the real runner, Plesk's Node settings, SSH into the real server. diff --git a/docs/gotchas.md b/docs/gotchas.md index 915af96..a8c42e8 100644 --- a/docs/gotchas.md +++ b/docs/gotchas.md @@ -47,6 +47,18 @@ Collected during the rewrite (September 2026); the progress log in - **Vitest 5 needs `@types/node` ≥ 22**; the config is `vitest.config.mts` because `package.json` has no `"type": "module"`. +## Deploy (Gitea Actions) + +- **`~` in an rsync `-e` string is not your `$HOME`.** rsync passes it to ssh without a shell, + and ssh expands `~` from the passwd entry. In a job container those can differ, so a key + written to `$HOME/.ssh` isn't found and `known_hosts` is read from somewhere else. The workflow + uses absolute paths (`SSH_DIR`) and `UserKnownHostsFile`. Found in a local dry run. +- **The deploy target is Plesk's own subdomain folder** (`calendar.nachklang.art/`), so rsync + `--delete` must exclude what Plesk or Passenger keep there (`tmp/`, `.well-known/`). The first + deploy replaces the Angular build - back it up first, and switch Plesk to the Node app right + after the run, because the folder no longer works as a static site. +- **Disable the Jenkins job before merging to master**, or it runs `ng build` on the next push. + ## shadcn / Base UI - **`npx shadcn add` imports `cn` from the npm package `cn`** and adds it (plus `next-themes` for the diff --git a/docs/rewrite-plan.md b/docs/rewrite-plan.md index 37b81bc..dc63663 100644 --- a/docs/rewrite-plan.md +++ b/docs/rewrite-plan.md @@ -401,6 +401,20 @@ Next; README links the docs. Deployment prep: standalone output doesn't serve `. own, so `postbuild` now copies it; verified by running `.next/standalone/server.js` on :4300 (styled page, CSS/JS 200, `/admin` redirect). +**Deploy via Gitea Actions - prepared 2026-11-08 (uncommitted).** Replaces the Jenkins job +(`npm ci`, `ng build`, `cp` into the webroot through a shared path, commit status via curl). +Decisions with the user: build in the runner and deliver over SSH/rsync as the subscription user +`nachklang` (option B; no mounted host paths, no containerised app for performance reasons); no +release folders, rsync straight into the app root, rollback = redeploy; app root = the folder Plesk created for the subdomain (user: don't touch Plesk's layout), so `--delete` excludes `tmp/` and `.well-known/`; API workflow later. +`.gitea/workflows/deploy.yml` follows the Buddygotchi workflow's shape (test job on every push/PR, +deploy job on master, `ubuntu-latest` runner image). Facts from the user: runner is a Docker +container on the same server, Passenger has Node 26.13.0, SSH for `nachklang` is currently +"Forbidden". Verified locally: actionlint clean; the deploy steps against a throwaway SSH server +(including stale-file removal, `tmp/` kept, wrong host key aborts). The dry run found the +`~`-expansion bug (see gotchas). Setup and switchover order: `docs/deployment.md`. +To do after the first real deploy: record what turned out differently in `deployment.md`, and +write the procedure into the user's PKM (requested). + Local test environment (throwaway, nothing points at shared infra): - `podman run -d --name nk-calendar-test -p 3306:3306 -e TZ=Europe/Berlin -e MARIADB_ROOT_PASSWORD=… --tmpfs /var/lib/mysql -v API/docker/init:/docker-entrypoint-initdb.d:ro -v API/sql:/migrations:ro mariadb:11` - in-memory, seeded by the API's own dev scripts, incl. the `dev@nachklang.art` account.