Files
Calendar_Frontend/docs/deployment.md
T
PaddyandClaude Opus 5.5 b0cd657fd9 Deploy with Gitea Actions instead of Jenkins
Tests every push and pull request (lint, typecheck, Vitest, production
build); pushes to master build the standalone bundle in the runner and
rsync it over SSH as the subscription user into the subdomain's Plesk
folder, then restart Passenger via tmp/restart.txt. No mounted host paths;
rsync --delete leaves tmp/ and .well-known/ alone. Optional smoke test once
DEPLOY_SMOKE_URL is set.

Setup (deploy key, pinned host key, Gitea secrets and variables, Plesk
Node.js settings) and the switchover order are in docs/deployment.md.
Checked locally with actionlint and against a throwaway SSH server, which
also caught "~" in the rsync -e string resolving to the wrong home.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-08 21:09:19 +01:00

8.7 KiB

Deployment and switchover

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.

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:<app root>
                                                                        └─ touch tmp/restart.txt
browser ──https──▶ Plesk (nginx + Passenger) ──▶ <app root>/server.js

Pull requests only run the test job.

Why SSH and not mounted paths

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.

One-time setup

1. SSH access for nachklang (Plesk)

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.

2. Deploy key

On any machine:

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:

ssh-keyscan -t ed25519 <DEPLOY_HOST>                       # → 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

  • 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.