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>
159 lines
8.7 KiB
Markdown
159 lines
8.7 KiB
Markdown
# 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:
|
|
|
|
```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
|
|
|
|
- **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.
|