Compare commits
5
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
c9c40af382 | ||
|
|
ae4f153482 | ||
|
|
1bfcc7a079 | ||
|
|
43c7dccc9f | ||
|
|
c4661d1dc0 |
No files matched your search
@@ -0,0 +1,106 @@
|
|||||||
|
# Tests every push and pull request; deploys pushes to master to the Plesk server.
|
||||||
|
# Setup and what the deploy may touch: docs/deployment.md.
|
||||||
|
#
|
||||||
|
# Same pattern as the calendar frontend (Calendar_Frontend/.gitea/workflows/deploy.yml): build here,
|
||||||
|
# deliver over SSH as the Plesk subscription user, restart Passenger. Unlike there, the app folder
|
||||||
|
# also holds things the deploy must never touch (.env with the secrets, logs/, tmp/), so only the
|
||||||
|
# app's own folders are synced with --delete and nothing is deleted at the top level.
|
||||||
|
name: Test and deploy
|
||||||
|
|
||||||
|
on:
|
||||||
|
push:
|
||||||
|
branches: [master]
|
||||||
|
pull_request:
|
||||||
|
|
||||||
|
jobs:
|
||||||
|
# One job, not test + deploy: every job starts in a fresh container, so two jobs meant checking out,
|
||||||
|
# setting up Node and running `npm ci` twice (~2 min each, 2026-11-08). The deploy steps only run
|
||||||
|
# for pushes to master; on pull requests the job ends after the tests. The condition is spelled out
|
||||||
|
# on every deploy step rather than stored in an env flag: a flag compared as a string ('true') would
|
||||||
|
# skip the deploy silently - and green - if the runner ever rendered the boolean differently.
|
||||||
|
test-and-deploy:
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
env:
|
||||||
|
DEPLOY_HOST: ${{ vars.DEPLOY_HOST }}
|
||||||
|
DEPLOY_PORT: ${{ vars.DEPLOY_PORT }}
|
||||||
|
DEPLOY_USER: ${{ vars.DEPLOY_USER }}
|
||||||
|
DEPLOY_PATH: ${{ vars.DEPLOY_PATH }}
|
||||||
|
# Absolute on purpose: rsync passes its -e string to ssh without a shell, and ssh expands "~"
|
||||||
|
# from the passwd entry, not $HOME (see the calendar frontend's docs/gotchas.md).
|
||||||
|
SSH_DIR: /tmp/deploy-ssh
|
||||||
|
steps:
|
||||||
|
- uses: actions/checkout@v4
|
||||||
|
- uses: actions/setup-node@v4
|
||||||
|
with:
|
||||||
|
node-version-file: .nvmrc
|
||||||
|
- run: npm ci
|
||||||
|
- run: npx tsc --noEmit
|
||||||
|
# Unit tests only. The integration tests (npm run test:integration) start their own MariaDB
|
||||||
|
# container and aren't run here.
|
||||||
|
# FEEDBACK_IP_SALT (which the Jenkins job exported) isn't needed: vitest.config.ts sets one.
|
||||||
|
- run: npm test
|
||||||
|
|
||||||
|
- name: Build
|
||||||
|
if: github.event_name == 'push' && github.ref == 'refs/heads/master'
|
||||||
|
run: npm run build
|
||||||
|
# Only runtime dependencies go to the server (no typescript, vitest, ...).
|
||||||
|
- name: Prune dev dependencies
|
||||||
|
if: github.event_name == 'push' && github.ref == 'refs/heads/master'
|
||||||
|
run: npm prune --omit=dev
|
||||||
|
|
||||||
|
- name: SSH setup
|
||||||
|
if: github.event_name == 'push' && github.ref == 'refs/heads/master'
|
||||||
|
env:
|
||||||
|
DEPLOY_SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
|
||||||
|
DEPLOY_KNOWN_HOSTS: ${{ secrets.DEPLOY_KNOWN_HOSTS }}
|
||||||
|
run: |
|
||||||
|
test -n "$DEPLOY_HOST" && test -n "$DEPLOY_USER" && test -n "$DEPLOY_PATH"
|
||||||
|
if ! command -v rsync >/dev/null 2>&1 || ! command -v ssh >/dev/null 2>&1; then
|
||||||
|
apt-get update && apt-get install -y --no-install-recommends rsync openssh-client
|
||||||
|
fi
|
||||||
|
install -m 700 -d "$SSH_DIR"
|
||||||
|
printf '%s\n' "$DEPLOY_SSH_KEY" > "$SSH_DIR/key"
|
||||||
|
chmod 600 "$SSH_DIR/key"
|
||||||
|
# Pinned host key, never trust-on-first-use.
|
||||||
|
printf '%s\n' "$DEPLOY_KNOWN_HOSTS" > "$SSH_DIR/known_hosts"
|
||||||
|
|
||||||
|
- name: Upload
|
||||||
|
if: github.event_name == 'push' && github.ref == 'refs/heads/master'
|
||||||
|
run: |
|
||||||
|
rsh="ssh -p ${DEPLOY_PORT:-22} -i $SSH_DIR/key -o UserKnownHostsFile=$SSH_DIR/known_hosts -o IdentitiesOnly=yes -o BatchMode=yes"
|
||||||
|
target="$DEPLOY_USER@$DEPLOY_HOST:$DEPLOY_PATH"
|
||||||
|
# The app's own folders, each mirrored exactly (--delete within the folder only).
|
||||||
|
# src/ is needed at runtime: swagger-jsdoc reads the route docs from src/models/**/*.ts.
|
||||||
|
for dir in dist src public node_modules; do
|
||||||
|
rsync -az --delete -e "$rsh" "$dir/" "$target/$dir/"
|
||||||
|
done
|
||||||
|
# Single files at the top level, without --delete: .env, logs/ and tmp/ live there too.
|
||||||
|
# package.json is what makes Node treat dist/ as ES modules ("type": "module").
|
||||||
|
rsync -az -e "$rsh" package.json package-lock.json "$target/"
|
||||||
|
|
||||||
|
- name: Restart
|
||||||
|
if: github.event_name == 'push' && github.ref == 'refs/heads/master'
|
||||||
|
run: |
|
||||||
|
# Passenger restarts the app on its next request when tmp/restart.txt is touched.
|
||||||
|
ssh -p "${DEPLOY_PORT:-22}" -i "$SSH_DIR/key" -o "UserKnownHostsFile=$SSH_DIR/known_hosts" \
|
||||||
|
-o IdentitiesOnly=yes -o BatchMode=yes "$DEPLOY_USER@$DEPLOY_HOST" \
|
||||||
|
"mkdir -p '$DEPLOY_PATH/tmp' && touch '$DEPLOY_PATH/tmp/restart.txt'"
|
||||||
|
|
||||||
|
# Set DEPLOY_SMOKE_URL to an endpoint that must answer 200 without a session, e.g.
|
||||||
|
# https://api.nachklang.art/calendar/events/public/json (what nachklang.art itself reads).
|
||||||
|
- name: Smoke test
|
||||||
|
if: github.event_name == 'push' && github.ref == 'refs/heads/master' && vars.DEPLOY_SMOKE_URL != ''
|
||||||
|
env:
|
||||||
|
DEPLOY_SMOKE_URL: ${{ vars.DEPLOY_SMOKE_URL }}
|
||||||
|
run: |
|
||||||
|
# Passenger starts the app on the first request after the restart; give it a moment.
|
||||||
|
for _ in 1 2 3 4 5 6; do
|
||||||
|
if curl -fsS -o /dev/null "$DEPLOY_SMOKE_URL"; then echo "OK: $DEPLOY_SMOKE_URL"; exit 0; fi
|
||||||
|
sleep 5
|
||||||
|
done
|
||||||
|
echo "Smoke test failed: $DEPLOY_SMOKE_URL"
|
||||||
|
exit 1
|
||||||
|
|
||||||
|
- name: Remove key
|
||||||
|
if: always() && github.event_name == 'push' && github.ref == 'refs/heads/master'
|
||||||
|
run: rm -f "$SSH_DIR/key"
|
||||||
@@ -8,7 +8,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
|||||||
npm run build # Compile TypeScript → dist/
|
npm run build # Compile TypeScript → dist/
|
||||||
npm run start # Build and start (tsc && node ./dist/app.js)
|
npm run start # Build and start (tsc && node ./dist/app.js)
|
||||||
npm run debug # Start with DEBUG=* environment variable
|
npm run debug # Start with DEBUG=* environment variable
|
||||||
npm run test # Run the vitest suite once with coverage (lcov + testResults/sonar-report.xml)
|
npm run test # Run the vitest suite once with coverage (text summary + lcov in coverage/)
|
||||||
npm run test:watch # vitest in watch mode
|
npm run test:watch # vitest in watch mode
|
||||||
npm run test:integration # Admin-module tests against a throwaway MariaDB (needs docker or podman)
|
npm run test:integration # Admin-module tests against a throwaway MariaDB (needs docker or podman)
|
||||||
```
|
```
|
||||||
@@ -18,6 +18,12 @@ Run a single test file:
|
|||||||
npx vitest run test/some.test.ts
|
npx vitest run test/some.test.ts
|
||||||
```
|
```
|
||||||
|
|
||||||
|
**Deploys** run in Gitea Actions (`.gitea/workflows/deploy.yml`, since 2026-11-08; Jenkins is
|
||||||
|
retired): every push/PR runs `tsc` and the unit tests, pushes to master build, prune dev
|
||||||
|
dependencies and rsync `dist/`, `src/`, `public/`, `node_modules/` and `package.json` to Plesk over
|
||||||
|
SSH. `.env`, `logs/` and `tmp/` on the server are never touched; SQL migrations stay manual.
|
||||||
|
Details: `docs/deployment.md`.
|
||||||
|
|
||||||
## Architecture
|
## Architecture
|
||||||
|
|
||||||
Express.js REST API in TypeScript with a service-oriented layering. Domains: `Calendar` (events, users), `Feedback` (concert feedback forms, mounted at `/feedback`, backed by its own `FEEDBACK_DB` — see `src/models/feedback/`: public submission flow, admin CRUD, reporting, and a Salesforce newsletter-sync integration), `Tickets` (mounted at `/tickets`), and `Admin` (identity and permissions, mounted at `/admin`, backed by `ADMIN_DB` — see below).
|
Express.js REST API in TypeScript with a service-oriented layering. Domains: `Calendar` (events, users), `Feedback` (concert feedback forms, mounted at `/feedback`, backed by its own `FEEDBACK_DB` — see `src/models/feedback/`: public submission flow, admin CRUD, reporting, and a Salesforce newsletter-sync integration), `Tickets` (mounted at `/tickets`), and `Admin` (identity and permissions, mounted at `/admin`, backed by `ADMIN_DB` — see below).
|
||||||
|
|||||||
@@ -0,0 +1,116 @@
|
|||||||
|
# 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).
|
||||||
Generated
+6
-757
File diff suppressed because it is too large.
Load diff
+1
-4
@@ -23,7 +23,6 @@
|
|||||||
"@better-auth/passkey": "^1.7.2",
|
"@better-auth/passkey": "^1.7.2",
|
||||||
"app-root-path": "^3.0.0",
|
"app-root-path": "^3.0.0",
|
||||||
"axios": "^1.20.0",
|
"axios": "^1.20.0",
|
||||||
"bcrypt": "^5.0.1",
|
|
||||||
"better-auth": "^1.7.2",
|
"better-auth": "^1.7.2",
|
||||||
"cors": "^2.8.5",
|
"cors": "^2.8.5",
|
||||||
"debug": "^4.3.1",
|
"debug": "^4.3.1",
|
||||||
@@ -41,7 +40,6 @@
|
|||||||
},
|
},
|
||||||
"devDependencies": {
|
"devDependencies": {
|
||||||
"@types/app-root-path": "^1.2.4",
|
"@types/app-root-path": "^1.2.4",
|
||||||
"@types/bcrypt": "^3.0.1",
|
|
||||||
"@types/cors": "^2.8.19",
|
"@types/cors": "^2.8.19",
|
||||||
"@types/debug": "^4.1.5",
|
"@types/debug": "^4.1.5",
|
||||||
"@types/express": "^4.17.15",
|
"@types/express": "^4.17.15",
|
||||||
@@ -56,8 +54,7 @@
|
|||||||
"source-map-support": "^0.5.19",
|
"source-map-support": "^0.5.19",
|
||||||
"supertest": "^7.2.2",
|
"supertest": "^7.2.2",
|
||||||
"typescript": "^5.9.3",
|
"typescript": "^5.9.3",
|
||||||
"vitest": "^5.0.0",
|
"vitest": "^5.0.0"
|
||||||
"vitest-sonar-reporter": "^3.0.0"
|
|
||||||
},
|
},
|
||||||
"overrides": {
|
"overrides": {
|
||||||
"better-auth": {
|
"better-auth": {
|
||||||
|
|||||||
@@ -1,6 +0,0 @@
|
|||||||
sonar.projectKey=nk-api
|
|
||||||
sonar.sources=src
|
|
||||||
sonar.tests=test
|
|
||||||
sonar.language=ts
|
|
||||||
sonar.javascript.lcov.reportPaths=coverage/lcov.info
|
|
||||||
sonar.testExecutionReportPaths=testResults/sonar-report.xml
|
|
||||||
@@ -14,10 +14,6 @@ export default defineConfig({
|
|||||||
env: {
|
env: {
|
||||||
FEEDBACK_IP_SALT: 'vitest-salt'
|
FEEDBACK_IP_SALT: 'vitest-salt'
|
||||||
},
|
},
|
||||||
reporters: [
|
|
||||||
'default',
|
|
||||||
['vitest-sonar-reporter', {outputFile: 'testResults/sonar-report.xml'}]
|
|
||||||
],
|
|
||||||
coverage: {
|
coverage: {
|
||||||
provider: 'v8',
|
provider: 'v8',
|
||||||
reporter: ['text-summary', 'lcov'],
|
reporter: ['text-summary', 'lcov'],
|
||||||
|
|||||||
Reference in new issue
Block a user