Files
API/docs/deployment.md
PaddyandClaude Opus 5.5 ae4f153482
Test and deploy / test-and-deploy (pull_request) Successful in 33s
Run tests and deploy in one Gitea Actions job
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>
2026-11-08 22:51:30 +01:00

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)

  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).