Files
plutoapi-v2/DEPLOYMENT.md
T
PaddyandClaude Opus 5.5 095815e0f3
Test and deploy / test-and-deploy (pull_request) Successful in 30s
Deploy with Gitea Actions instead of Jenkins on Node 26, drop SonarQube
One job: npm ci, tsc --noEmit, npm test on Node 26; on pushes to master
it builds, prunes dev dependencies and rsyncs dist/, src/ (Swagger reads
it) and node_modules/ over SSH as plesk-plutodev, then restarts Passenger
and smoke-tests /docs/. The server's .env, logs/, tmp/ and public/ are
never touched - .env is no longer generated by CI but kept on the server.

Plesk moves from Node 12.22.12 to 26 with this; the bundle built on 26
also starts on 12, so the order of deploy and Plesk switch doesn't
matter. SonarQube leftovers are gone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 13:03:00 +01:00

5.7 KiB

Deployment

api.plutodev.de runs on the Plesk server as a Node.js app (Phusion Passenger) and is deployed by Gitea Actions (.gitea/workflows/deploy.yml), which replaces the Jenkins job (switchover 2026-11). Same workflow as Paddy/api.pmueller.me and the Nachklang API; the reusable how-to is 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 (Node 26)
                                           └─ (master only) build, prune dev deps ─ rsync over SSH ─▶
                                              plesk-plutodev@pmueller.me:/var/www/vhosts/plutodev.de/api.plutodev.de
                                              + tmp/restart.txt

Plesk (as configured, 2026-11-16)

Websites & Domains → api.plutodev.de → Node.js:

Setting Value
Node.js version 26 - switched from 12.22.12 (end of life since 2022) with the Gitea switchover, see "Node version"
Application root /api.plutodev.de (= /var/www/vhosts/plutodev.de/api.plutodev.de)
Document root /api.plutodev.de/public
Application startup file dist/app.js
Application mode production
Environment variable PORT=443 (Passenger takes over the port)

Configuration: .env lives on the server

The app reads its settings from .env in the app root (dotenv): database credentials and names, TWITCH_HIGHLIGHTS_ACCESS_KEY, HCAPTCHA_SECRET, ... The Jenkins job wrote that file on every deploy from its own credentials. The workflow never touches it: since the switchover the .env on the server is the source of truth and is edited there (Plesk file manager), or the values move to Plesk's Node.js → Environment → Secrets. Nothing secret is stored in Gitea for this app.

The code also reads CRAWLER_ACCESS_KEY, which the Jenkins-generated .env never contained (2026-11-16) - either unused or set elsewhere; not checked.

What the deploy touches - and what it must not

Path How Why it's needed at runtime
dist/ mirrored (--delete inside) the compiled app
src/ mirrored swagger-jsdoc reads ./src/models/**/*.router.ts for /docs
node_modules/ mirrored, production dependencies only (npm prune --omit=dev) runtime dependencies
package.json, package-lock.json copied, no delete (CommonJS - the app ran without them)

Never touched: .env, logs/ (Winston), tmp/ (Passenger's restart.txt), public/ (Passenger's document root; gitignored in this repo, and Jenkins never copied it either).

Node version

Until 2026-11-16 Plesk ran this app on Node 12.22.12; with the switchover it moves to 26 (.nvmrc 26, so CI builds and tests with the same version).

Checked locally (2026-11-16), as x86_64 like the runner (podman --platform linux/amd64): npm ci on Node 26 downloads bcrypt 5.0.1's prebuilt N-API binary (napi-v3), tsc, the test, build and prune pass, and the pruned bundle starts under Node 26 and under Node 12.22.12 (/docs/ 200, bcrypt loads). So the order doesn't matter: the first deploy may land while Plesk still says 12, then switch Plesk to 26. Database queries were not exercised (no DB) - check one endpoint per app after the switch.

Don't test this on the Mac's default (arm64) containers: bcrypt 5.0.1 has no arm64 prebuilt, so npm compiles it there, and that compile fails on Node 26 - a local artefact, not what the runner does.

Gitea settings

The repo belongs to the organisation PlutoDev, so user-level settings of Paddy don't apply. On the organisation (PlutoDev → Settings → Actions), for all PlutoDev repos: secrets DEPLOY_SSH_KEY (the shared private deploy key gitea-actions Paddy - PlutoDev is a private project now), DEPLOY_KNOWN_HOSTS ([pmueller.me]:42069 ssh-ed25519 …, same server); variables DEPLOY_HOST=pmueller.me, DEPLOY_PORT=42069, DEPLOY_USER=plesk-plutodev.

On this repository (plutoapi-v2 → Settings → Actions → Variables):

Variable Value
DEPLOY_PATH /var/www/vhosts/plutodev.de/api.plutodev.de
DEPLOY_SMOKE_URL https://api.plutodev.de/docs/

Switchover

  1. SSH for plesk-plutodev (was /bin/false, set to /bin/bash 2026-11-16, done): the shared public key appended to /var/www/vhosts/plutodev.de/.ssh/authorized_keys (.ssh 700, file 600), the user added to the key-only Match User … line in /etc/ssh/sshd_config.
  2. Pause the Jenkins job (done 2026-11-16). Its credentials (DB_USER, DB_PASSWORD, TWITCH_HIGHLIGHTS_ACCESS_KEY, HCAPTCHA_SECRET) can be deleted from Jenkins afterwards - they're in the server's .env.
  3. Fix file ownership (as root): ls -ld . first (the folder keeps its group), then find . -mindepth 1 ! -user plesk-plutodev -exec chown -h plesk-plutodev:psacln {} + - -h for the symlinks in node_modules/.bin/.
  4. Set the variables, open a PR → green run → merge → watch the deploy, check /docs/.
  5. Plesk → api.plutodev.de → Node.js: version 26, restart; check /docs/ and one endpoint per app.

Rollback: revert the commit on master; the workflow deploys the previous state.

Cleaned up with the switchover (2026-11-16)

  • SonarQube is gone: sonar-project.properties, jest-sonar-reporter, the --coverage --testResultsProcessor flags and the jestSonar config.

Checked locally (2026-11-16)

  • actionlint: no findings.
  • node:26-bookworm (x86_64): npm ci, tsc --noEmit, npm test, build, npm prune --omit=dev; the bundle then ran under Node 26 and Node 12 (see "Node version").

Not checked: the workflow on the real runner.