# Deployment The API runs on the Plesk server as a Node.js app (Phusion Passenger) and is deployed by **Gitea Actions** (`.gitea/workflows/deploy.yml`), which replaced the Jenkins job on 2026-11-08. Same pattern as the calendar frontend; the reusable how-to (server facts, one-time setup, gotchas) is in `Calendar_Frontend/docs/deployment.md` and in Patrick's PKM ("Jenkins to Gitea Actions for a Plesk Node.js App"). ``` push to master ──▶ Gitea ──▶ runner (container on the server) └─ one job: npm ci, tsc --noEmit, npm test (unit tests) └─ (master only) build, prune dev deps ─ rsync over SSH ─▶ plesk-nachklang@nachklang.art: + tmp/restart.txt ``` Pull requests run the same job up to the tests; the deploy steps only run for pushes to master. It used to be two jobs, which ran `npm ci` twice (~2 min each); merged into one on 2026-11-08. ## Plesk (as configured, 2026-11-08) *Websites & Domains → api.nachklang.art → Node.js*: | Setting | Value | |---|---| | Node.js version | 26.13.0 | | Application root | `/api.nachklang.art` (= `/var/www/vhosts/nachklang.art/api.nachklang.art`) | | Document root | `/api.nachklang.art/public` | | Application startup file | `dist/app.js` | | Application mode | production | | Environment variable | `PORT=443` (Passenger takes over the port; `app.ts` exits without `PORT`) | ## What the deploy touches - and what it must not The app root holds more than the build, so the workflow syncs **only the app's own parts**: | Path | How | Why it's needed at runtime | |---|---|---| | `dist/` | mirrored (`--delete` inside) | the compiled app | | `src/` | mirrored | swagger-jsdoc reads the route docs from `src/models/**/*.router.ts` / `*.interface.ts` for `/docs` | | `public/` | mirrored | Passenger's document root | | `node_modules/` | mirrored, production dependencies only (`npm prune --omit=dev`) | runtime dependencies | | `package.json`, `package-lock.json` | copied, no delete | `"type": "module"` makes Node load `dist/` as ES modules | **Never touched** (nothing is deleted at the top level): `.env` (the secrets; `dotenv` reads it from the app root), `logs/` (Winston writes there, relative to the app root), `tmp/` (Passenger's `restart.txt`), and anything else in that folder. The Jenkins job copied `dist/`, `src/` and `node_modules/` with `cp` (never deleting, so stale files piled up) and never `package.json` or `public/`; the first rsync deploy cleans that up. **SQL migrations are not part of the deploy.** Files under `sql/` are still applied by hand, before the deploy that needs them. ## Gitea settings Shared by all Nachklang repos, on the organisation (*Nachklang → Settings → Actions*): secrets `DEPLOY_SSH_KEY`, `DEPLOY_KNOWN_HOSTS`; variables `DEPLOY_HOST=nachklang.art`, `DEPLOY_PORT=42069`, `DEPLOY_USER=plesk-nachklang`. On this repository (*API → Settings → Actions → Variables*): | Variable | Value | |---|---| | `DEPLOY_PATH` | `/var/www/vhosts/nachklang.art/api.nachklang.art` | | `DEPLOY_SMOKE_URL` | `https://api.nachklang.art/calendar/events/public/json` | The smoke test only needs an endpoint that answers 200 without a session; the public calendar feed is the one nachklang.art itself depends on. ## Switchover (done once) 1. Pause the Jenkins API job (done 2026-11-08). 1a. **Fix file ownership** (as root): Jenkins deployed as **root**, so `dist/`, `src/` and `node_modules/` were `root:root`, and the first Gitea deploy failed with rsync "Operation not permitted" / "Permission denied" - the subscription user can't change root's files. Fixed with `chown -R plesk-nachklang:psacln dist src node_modules` in the app root (the group of the files the app creates itself, e.g. `.env`, `logs/`); then re-run the failed job. Check: `find . ! -user plesk-nachklang` prints nothing. 2. Set `DEPLOY_PATH` and `DEPLOY_SMOKE_URL`. 3. Open a PR → green run → merge → watch the deploy steps. Unlike the calendar there is no gap: the folder keeps working while files are replaced, and Passenger restarts on the next request. 4. Check `https://api.nachklang.art/docs` and the calendar/feedback/tickets apps. Rollback: revert the commit on master; the workflow deploys the previous state. ## Checked locally (2026-11-08) - `actionlint`: no findings. - In a clean `node:26` container (26.13.0, no `.env`): `npm ci`, `tsc --noEmit`, all 233 unit tests, build, `npm prune --omit=dev`. - The pruned bundle, laid out like the server folder with a test `.env`, started with `node dist/app.js` against a throwaway MariaDB: public JSON 200, iCal `text/calendar`, `/docs` 200 including the subscriptions route (so `src/` is read), `/admin/me` 401, `logs/` created in the app root. - The workflow's upload step against a throwaway SSH server with a folder like the real one: `.env`, `logs/`, `tmp/` and an unrelated top-level file kept; a stale package in `node_modules/` and a stale file in `dist/` removed; `package.json` updated. Not checked: the workflow on the real runner. ## Notes - There was **no `package.json` on the server** before the first rsync deploy (Jenkins never copied it); `dist/app.js` still ran as ES modules, probably because Node ≥ 22 detects ES module syntax on its own [inference, not checked]. The deploy now ships `package.json`, so it doesn't depend on that. - A failed upload leaves new and old files mixed in `dist/`, but the running app is unaffected: the restart step is skipped, so Passenger keeps the old code in memory until the next deploy (or an unplanned restart - fix and re-run soon). - `bcrypt` was removed on 2026-11-08: nothing imported it any more (passwords moved to better-auth, which hashes with its own scrypt). It was the only production dependency with a native build step. - `FEEDBACK_IP_SALT`, which the Jenkins test step exported, isn't needed in CI: `vitest.config.ts` sets one for the test run. - SonarQube isn't used any more; `sonar-project.properties`, the `vitest-sonar-reporter` and its `testResults/sonar-report.xml` were removed on 2026-11-08 (the Jenkins job ran the tests only to feed Sonar's coverage).