Files
API/docs/deployment.md
T
PaddyandClaude Opus 5.5 43c7dccc9f
Test and deploy / test (pull_request) Successful in 32s
Test and deploy / deploy (pull_request) Skipped
Deploy with Gitea Actions instead of Jenkins
Tests every push and pull request (tsc, unit tests); pushes to master build,
prune dev dependencies and rsync dist/, src/, public/, node_modules/ and
package.json over SSH as the Plesk subscription user, then restart Passenger
via tmp/restart.txt. Only the app's own folders are mirrored with --delete;
.env, logs/ and tmp/ in the app root are never touched. Optional smoke test
via DEPLOY_SMOKE_URL. Same pattern as the calendar frontend; setup and what
the deploy may touch are in docs/deployment.md.

Also removes leftovers: bcrypt (unused since better-auth, and the only
production dependency with a native build) and the SonarQube setup
(sonar-project.properties, vitest-sonar-reporter).

Checked locally: actionlint; in a clean node:26 container npm ci, tsc,
233 unit tests, build and prune; the pruned bundle started against a
throwaway MariaDB (public feed, iCal, /docs, /admin/me); the upload step
against a throwaway SSH server with .env, logs/ and tmp/ in place.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-08 22:35:57 +01:00

4.9 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)
                               ├─ test job:   npm ci, tsc --noEmit, npm test (unit tests)
                               └─ deploy job: npm ci, build, prune dev deps ─ rsync over SSH ─▶
                                              plesk-nachklang@nachklang.art:<app root>  + tmp/restart.txt

Pull requests only run the test job.

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).
  2. Set DEPLOY_PATH and DEPLOY_SMOKE_URL.
  3. Open a PR → green test job → merge → watch the deploy job. 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

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