Rewrite the calendar frontend in Next.js #22

Merged
Paddy merged 3 commits from feature/nextjs-rewrite into master 2026-11-08 20:54:10 +00:00
5 changed files with 285 additions and 54 deletions
Showing only changes of commit b0cd657fd9 - Show all commits

No files matched your search

+116
View File
@@ -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"
+1 -1
View File
@@ -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
+142 -53
View File
@@ -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:<app root>
└─ touch tmp/restart.txt
browser ──https──▶ Plesk (nginx + Passenger) ──▶ <app root>/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 <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
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.
+12
View File
@@ -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
+14
View File
@@ -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.