diff --git a/docs/deployment.md b/docs/deployment.md index e34abf5..bce4c9d 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -8,7 +8,7 @@ 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: + └─ deploy job: build ─ rsync over SSH ─▶ plesk-nachklang@server: └─ touch tmp/restart.txt browser ──https──▶ Plesk (nginx + Passenger) ──▶ /server.js ``` @@ -18,7 +18,7 @@ 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 +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 @@ -26,55 +26,96 @@ into the app root, and a rollback is a redeploy of an older commit. ## One-time setup -### 1. SSH access for `nachklang` (Plesk) +### 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 (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`. +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 calendar-deploy -C "gitea-actions Calendar_Frontend" +ssh-keygen -t ed25519 -N "" -f nachklang-deploy -C "gitea-actions Nachklang" ``` -- 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. +**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 -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 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 -t ed25519 # → the secret DEPLOY_KNOWN_HOSTS +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. 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. +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 repository settings +### 4. Gitea settings -*Calendar_Frontend → Settings → Actions* (Actions must be enabled for the repo): +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.*`). -| 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** | +| 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. diff --git a/docs/gotchas.md b/docs/gotchas.md index a8c42e8..cfc99bc 100644 --- a/docs/gotchas.md +++ b/docs/gotchas.md @@ -57,6 +57,11 @@ Collected during the rewrite (September 2026); the progress log in `--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. +- **Plesk's chrooted SSH shell is broken on this server**: `bash` segfaults in the chroot copy + under `/var/www/vhosts/nachklang.art`, so sessions close right after login (and the command of + an `ssh host 'cmd'` never runs, exit 255). The deploy user uses plain `/bin/bash` instead. +- **SSH is on port 42069**, not 22 (22 is closed); the deploy user is `plesk-nachklang`, not + `nachklang`. - **Disable the Jenkins job before merging to master**, or it runs `ng build` on the next push. ## shadcn / Base UI