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>
103 lines
4.9 KiB
Markdown
103 lines
4.9 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)
|
|
├─ 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).
|