Test and deploy / test-and-deploy (pull_request) Successful in 33s
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>
117 lines
6.1 KiB
Markdown
117 lines
6.1 KiB
Markdown
# 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).
|