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>
6.1 KiB
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:<app root> + 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)
- Pause the Jenkins API job (done 2026-11-08).
1a. Fix file ownership (as root): Jenkins deployed as root, so
dist/,src/andnode_modules/wereroot:root, and the first Gitea deploy failed with rsync "Operation not permitted" / "Permission denied" - the subscription user can't change root's files. Fixed withchown -R plesk-nachklang:psacln dist src node_modulesin 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-nachklangprints nothing. - Set
DEPLOY_PATHandDEPLOY_SMOKE_URL. - 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.
- Check
https://api.nachklang.art/docsand 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:26container (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 withnode dist/app.jsagainst a throwaway MariaDB: public JSON 200, iCaltext/calendar,/docs200 including the subscriptions route (sosrc/is read),/admin/me401,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 innode_modules/and a stale file indist/removed;package.jsonupdated.
Not checked: the workflow on the real runner.
Notes
-
There was no
package.jsonon the server before the first rsync deploy (Jenkins never copied it);dist/app.jsstill ran as ES modules, probably because Node ≥ 22 detects ES module syntax on its own [inference, not checked]. The deploy now shipspackage.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). -
bcryptwas 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.tssets one for the test run. -
SonarQube isn't used any more;
sonar-project.properties, thevitest-sonar-reporterand itstestResults/sonar-report.xmlwere removed on 2026-11-08 (the Jenkins job ran the tests only to feed Sonar's coverage).