Test and deploy / test-and-deploy (pull_request) Successful in 2m25s
Two jobs meant checking out, setting up Node and running npm ci (and in the frontend the build) twice, about two minutes each, because every job starts in a fresh container. Now one job tests and, for pushes to master only, deploys. The push-to-master condition is spelled out on every deploy step instead of an env flag compared to 'true', which would skip the deploy silently and stay green if the boolean were rendered differently. A failed test still stops the deploy (an if: without a status function implies success()). Docs: the one-job layout, and that Jenkins deployed as root - files it left in an app folder must be chowned to the subscription user before the first Gitea deploy (hit on the API). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
202 lines
12 KiB
Markdown
202 lines
12 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)
|
|
└─ one job: npm ci, lint, tsc, test, build
|
|
└─ (master only) rsync over SSH ─▶ plesk-nachklang@server:<app root>
|
|
└─ touch tmp/restart.txt
|
|
browser ──https──▶ Plesk (nginx + Passenger) ──▶ <app root>/server.js
|
|
```
|
|
|
|
Pull requests run the same job up to the build; the deploy steps only run for pushes to master.
|
|
It used to be two jobs (test, then deploy); since every job starts in a fresh container that meant
|
|
`npm ci` and the build twice (~2 min each), so they were merged on 2026-11-08.
|
|
|
|
## 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 (`plesk-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 `plesk-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`** (not chrooted).
|
|
`rsync` must be installed on the server (`command -v rsync`, else `apt-get install rsync`).
|
|
|
|
Why not chrooted (found 2026-11-08): with "/bin/bash (chrooted)" Plesk sets the shell to
|
|
`/opt/psa/bin/chrootsh`, which runs bash inside a copy of a system in the home folder
|
|
(`/var/www/vhosts/nachklang.art/{bin,lib,usr,…}`). That copy is broken on this server - `bash`
|
|
segfaults in it (`chroot … /bin/bash` → exit 139; it mixes libraries from several Debian releases,
|
|
likely a `libc` mismatch) - so every SSH session closed right after login. It also has no `rsync`.
|
|
Repairing it would mean rebuilding Plesk's chroot template and keeping it current after upgrades.
|
|
|
|
Trade-off accepted by the user: without the chroot the user can **read** world-readable files
|
|
elsewhere on the system (`/etc`, `/usr`, the process list), but **write** only where it could
|
|
before (its home with all Nachklang sites, `/tmp`); other subscriptions' homes stay unreadable
|
|
(`drwx--x---`, group `psaserv`). All Nachklang apps run as this one user anyway. A stricter
|
|
option, if ever wanted: force `command="rrsync /var/www/vhosts/nachklang.art",restrict` on the
|
|
deploy key in `authorized_keys` (rsync only, inside that folder, no shell) - the workflow would
|
|
then upload `tmp/restart.txt` instead of running `touch`, and `DEPLOY_PATH` would become relative.
|
|
|
|
**Key-only login.** Password and keyboard-interactive login are off for `plesk-nachklang`
|
|
(set up 2026-11-08): globally the server had `PasswordAuthentication yes` and
|
|
`KbdInteractiveAuthentication no`; a `Match User plesk-nachklang` block at the end of
|
|
`/etc/ssh/sshd_config` sets both to `no` for this user (confirmed by the user with `sshd -T -C`). Don't lock the account password
|
|
instead (`passwd -l`) - on Plesk the subscription user's password is also its FTP password
|
|
(inferred, not checked). Check with:
|
|
|
|
```bash
|
|
sudo sshd -T -C user=plesk-nachklang,host=test,addr=127.0.0.1 | grep -Ei '^(passwordauthentication|kbdinteractiveauthentication) '
|
|
ssh -p 42069 -o PubkeyAuthentication=no -o PreferredAuthentications=password plesk-nachklang@nachklang.art # must be refused at once
|
|
```
|
|
|
|
### 2. Deploy key
|
|
|
|
On any machine:
|
|
|
|
```bash
|
|
ssh-keygen -t ed25519 -N "" -f nachklang-deploy -C "gitea-actions Nachklang"
|
|
```
|
|
|
|
**One key for all Nachklang repos** (decided 2026-11-08: less upkeep; all apps run as the same
|
|
system user `plesk-nachklang` anyway - inferred from the shared `/var/www/vhosts/nachklang.art`, so
|
|
per-repo keys would only have added finer revocation, not isolation). The user generates and holds
|
|
the key; it never passes through Claude.
|
|
|
|
- Append `nachklang-deploy.pub` to `~/.ssh/authorized_keys` of `plesk-nachklang` on the server (as root:
|
|
`install -d -m 700` the `.ssh` folder owned by `plesk-nachklang`, file mode 600).
|
|
- The private key goes into Gitea as an **organisation** secret (below).
|
|
- Possible hardening later: restrict the key in `authorized_keys` (`restrict`, or `rrsync` limited
|
|
to one folder - would need the restart done by uploading `tmp/restart.txt` instead of `touch`).
|
|
|
|
### 3. Host key
|
|
|
|
SSH listens on **port 42069** (22 is closed). The job refuses any server whose host key it doesn't
|
|
already know. Get the line from a machine that can reach the server, and compare its fingerprint
|
|
with the server's own:
|
|
|
|
```bash
|
|
ssh-keyscan -p 42069 -t ed25519 nachklang.art # → the secret DEPLOY_KNOWN_HOSTS
|
|
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub # on the server: must match
|
|
```
|
|
|
|
Scanned 2026-11-08: `SHA256:iL7O98pO1vC4wDBVY88yo0xV5nwdxeE5vtAjqfOUpWI` for `[nachklang.art]:42069`.
|
|
|
|
`DEPLOY_HOST` must be reachable **from inside the runner's job containers**, which run on the
|
|
same server in a per-job Docker network (no `network` set in the runner's `config.yaml`). The
|
|
public hostname is used; *unverified* that a job container can reach the host on its public
|
|
address. If it can't, use the job network's gateway (or add
|
|
`--add-host=host.docker.internal:host-gateway` to the runner's `container.options`) and scan that
|
|
address for the known-hosts line.
|
|
|
|
### 4. Gitea settings
|
|
|
|
What every Nachklang repo shares goes on the **organisation** (*Nachklang → Settings → Actions*);
|
|
what is specific to this app on the **repository** (*Calendar_Frontend → Settings → Actions*;
|
|
Actions must be enabled for the repo). A repository value overrides an organisation value of the
|
|
same name. The workflow reads both the same way (`secrets.*`, `vars.*`).
|
|
|
|
| Level | Kind | Name | Value |
|
|
|---|---|---|---|
|
|
| Org | Secret | `DEPLOY_SSH_KEY` | private key from step 2 |
|
|
| Org | Secret | `DEPLOY_KNOWN_HOSTS` | line from step 3 |
|
|
| Org | Variable | `DEPLOY_HOST` | `nachklang.art` |
|
|
| Org | Variable | `DEPLOY_PORT` | `42069` |
|
|
| Org | Variable | `DEPLOY_USER` | `plesk-nachklang` |
|
|
| Repo | Variable | `DEPLOY_PATH` | `/var/www/vhosts/nachklang.art/calendar.nachklang.art` |
|
|
| Repo | Variable | `NEXT_PUBLIC_API_BASE_URL` | `https://api.nachklang.art` |
|
|
| Repo | Variable | `NEXT_PUBLIC_ADMIN_APP_URL` | `https://admin.nachklang.art` |
|
|
| Repo | 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 steps have 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.
|