- SSH on port 42069, deploy user plesk-nachklang, one deploy key for all Nachklang repos as a Gitea organisation secret (host, port and user as organisation variables; path and build values per repository). - Key-only login for the deploy user via a Match block in sshd_config. - Plain /bin/bash instead of Plesk's chrooted shell: bash segfaults in the chroot copy on this server, so every session closed right after login; the read-access trade-off and a stricter rrsync option are noted. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
200 lines
12 KiB
Markdown
200 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)
|
|
├─ test job: npm ci, lint, tsc, test, build
|
|
└─ deploy job: build ─ rsync over SSH ─▶ plesk-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 (`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 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.
|