Deploy with Gitea Actions instead of Jenkins
Tests every push and pull request (lint, typecheck, Vitest, production build); pushes to master build the standalone bundle in the runner and rsync it over SSH as the subscription user into the subdomain's Plesk folder, then restart Passenger via tmp/restart.txt. No mounted host paths; rsync --delete leaves tmp/ and .well-known/ alone. Optional smoke test once DEPLOY_SMOKE_URL is set. Setup (deploy key, pinned host key, Gitea secrets and variables, Plesk Node.js settings) and the switchover order are in docs/deployment.md. Checked locally with actionlint and against a throwaway SSH server, which also caught "~" in the rsync -e string resolving to the wrong home. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
5 files changed
+285
-54
No files matched your search
+142
-53
@@ -1,69 +1,158 @@
|
||||
# Deployment and switchover
|
||||
|
||||
How the Next.js app replaces the Angular build on `calendar.nachklang.art`. **The deploy itself is
|
||||
done by a person** (never by Claude). Steps marked *unverified* could not be checked without access
|
||||
to the Plesk server.
|
||||
How the Next.js app runs on the Plesk server and gets there. Deploys run in **Gitea Actions**
|
||||
(`.gitea/workflows/deploy.yml`), replacing the Jenkins job that copied the Angular build into the
|
||||
webroot. Steps marked *unverified* could not be checked without access to the server; the first
|
||||
real deploy settles them - record the outcome here.
|
||||
|
||||
## Order matters
|
||||
|
||||
1. **API first**: merge and deploy the API branch `feature/calendar-ical-escaping-subscriptions`
|
||||
(rebuild + restart; no new env vars - it uses the existing `API_BASE_URL` and
|
||||
`*_CREDENTIAL` values). The old Angular app keeps working against it; the new app's "Abonnieren"
|
||||
dialog needs it.
|
||||
2. **Then the frontend.**
|
||||
|
||||
## Build
|
||||
|
||||
Node version: `.nvmrc` says 26, copied from the API repo - *unverified* that Plesk offers it; use
|
||||
the version the API runs on.
|
||||
|
||||
```bash
|
||||
npm ci
|
||||
NEXT_PUBLIC_API_BASE_URL=https://api.nachklang.art \
|
||||
NEXT_PUBLIC_ADMIN_APP_URL=https://admin.nachklang.art \
|
||||
npm run build
|
||||
```
|
||||
push to master ──▶ Gitea ──▶ runner (Docker container on the Plesk server)
|
||||
├─ test job: npm ci, lint, tsc, test, build
|
||||
└─ deploy job: build ─ rsync over SSH ─▶ nachklang@server:<app root>
|
||||
└─ touch tmp/restart.txt
|
||||
browser ──https──▶ Plesk (nginx + Passenger) ──▶ <app root>/server.js
|
||||
```
|
||||
|
||||
- Both values are **inlined at build time** - they must be set for `npm run build`, not just at
|
||||
runtime. (Values from the Angular `environment.prod.ts`.)
|
||||
- `npm run build` runs `postbuild`, which copies `.next/static` into `.next/standalone/.next/static`.
|
||||
Without it the standalone server serves the pages without CSS and JS.
|
||||
- The build fetches the public events from the API to prerender `/`. If it can't reach the API it
|
||||
still succeeds.
|
||||
Pull requests only run the test job.
|
||||
|
||||
## Run (Plesk Node.js / Passenger)
|
||||
## Why SSH and not mounted paths
|
||||
|
||||
- Application startup file: `.next/standalone/server.js`.
|
||||
- The server listens on `PORT` (and `HOSTNAME`). Whether Passenger sets `PORT` itself or needs it
|
||||
configured is *unverified* - check how the feedback app is set up on the same server.
|
||||
- Optional runtime env: `API_BASE_URL` (internal address for the landing page's server-side fetch).
|
||||
- The subdomain changes from serving static files to a Node.js app. *Unverified* how Plesk handles
|
||||
that switch for an existing domain (document root vs. application root).
|
||||
Decided 2026-11-08. The Jenkins job wrote into the webroot through a path shared with the host.
|
||||
The workflow instead connects as the subscription's own system user (`nachklang`) with a
|
||||
dedicated deploy key: the job can only touch what that user can, files get the right owner
|
||||
without `chown`, nothing on the host is mounted into the runner, and the same steps work for any
|
||||
Node app on Plesk and keep working if the runner moves. No release folders: rsync writes straight
|
||||
into the app root, and a rollback is a redeploy of an older commit.
|
||||
|
||||
Checked locally (2026-09-28): `PORT=4300 node .next/standalone/server.js` serves `/` with events,
|
||||
CSS/JS (200), the favicon, and redirects `/admin` without a cookie to `/admin/login`.
|
||||
## One-time setup
|
||||
|
||||
## Things that must already be true (unchanged from the Angular app)
|
||||
### 1. SSH access for `nachklang` (Plesk)
|
||||
|
||||
The origin stays `https://calendar.nachklang.art`, so nothing should need changing - inferred from
|
||||
the Angular app already using the same cookie auth:
|
||||
*Websites & Domains → nachklang.art → Hosting & DNS → Hosting* (wording may differ by Plesk
|
||||
version): set **Access to the server over SSH** from "Forbidden" to `/bin/bash (chrooted)`.
|
||||
*Unverified* whether the chrooted environment includes `rsync`; if the first deploy fails with
|
||||
"rsync: command not found" on the remote side, switch to `/bin/bash`.
|
||||
|
||||
- the API's CORS list contains `https://calendar.nachklang.art` (verified in `app.factory.ts`);
|
||||
- the admin app's `NEXT_PUBLIC_ALLOWED_REDIRECT_ORIGINS` contains it (otherwise signing in lands on
|
||||
the admin start page instead of coming back);
|
||||
- the API's better-auth trusted origins contain it (otherwise sign-out fails).
|
||||
### 2. Deploy key
|
||||
|
||||
## Smoke test after the switch
|
||||
On any machine:
|
||||
|
||||
1. `/` loads styled, shows "Nächste Termine", and the Apple link opens a subscription.
|
||||
2. `/admin` while signed out → admin login → back to `/admin` after signing in.
|
||||
3. The list shows all calendars; an edit saves; "Abonnieren" lists links.
|
||||
4. An account without calendar permission sees "Kein Zugriff" (no redirect loop).
|
||||
5. "Abmelden" signs out and offers to sign in again.
|
||||
6. On a phone: list, "+" button, bottom sheet.
|
||||
7. An existing iCal subscription still updates (the feed URL is unchanged).
|
||||
```bash
|
||||
ssh-keygen -t ed25519 -N "" -f calendar-deploy -C "gitea-actions Calendar_Frontend"
|
||||
```
|
||||
|
||||
- Append `calendar-deploy.pub` to `~/.ssh/authorized_keys` of `nachklang` on the server (Plesk's
|
||||
SSH key management or the file manager; create `.ssh` with mode 700, the file with 600).
|
||||
- The private key `calendar-deploy` goes into Gitea as a secret (below), then delete the local copy.
|
||||
|
||||
### 3. Host key
|
||||
|
||||
The job refuses any server whose host key it doesn't already know. Get the line it needs from
|
||||
a machine that can reach the server, and compare its fingerprint with the server's own:
|
||||
|
||||
```bash
|
||||
ssh-keyscan -t ed25519 <DEPLOY_HOST> # → the secret DEPLOY_KNOWN_HOSTS
|
||||
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub # on the server: must match
|
||||
```
|
||||
|
||||
`DEPLOY_HOST` must be reachable **from inside the runner's job containers**, which run on the
|
||||
same server. The server's public hostname is the obvious choice; *unverified* that the server
|
||||
can reach itself on its public address. If it can't, use the Docker bridge gateway instead (on
|
||||
default Docker installs `172.17.0.1`) and scan that address for the known-hosts line.
|
||||
|
||||
### 4. Gitea repository settings
|
||||
|
||||
*Calendar_Frontend → Settings → Actions* (Actions must be enabled for the repo):
|
||||
|
||||
| Kind | Name | Value |
|
||||
|---|---|---|
|
||||
| Secret | `DEPLOY_SSH_KEY` | private key from step 2 |
|
||||
| Secret | `DEPLOY_KNOWN_HOSTS` | line(s) from step 3 |
|
||||
| Variable | `NEXT_PUBLIC_API_BASE_URL` | `https://api.nachklang.art` |
|
||||
| Variable | `NEXT_PUBLIC_ADMIN_APP_URL` | `https://admin.nachklang.art` |
|
||||
| Variable | `DEPLOY_HOST` | from step 3 |
|
||||
| Variable | `DEPLOY_USER` | `nachklang` |
|
||||
| Variable | `DEPLOY_PATH` | `/var/www/vhosts/nachklang.art/calendar.nachklang.art` |
|
||||
| Variable | `DEPLOY_PORT` | only if SSH isn't on 22 |
|
||||
| Variable | `DEPLOY_SMOKE_URL` | `https://calendar.nachklang.art/` - **only after step 5** |
|
||||
|
||||
The `NEXT_PUBLIC_*` values are inlined at build time; they are variables, not secrets, because
|
||||
they end up in the JavaScript every visitor downloads anyway.
|
||||
|
||||
`DEPLOY_PATH` is the folder Plesk created for the subdomain - the same one Jenkins copied the
|
||||
Angular build into (decided 2026-11-08: don't move away from Plesk's own layout). rsync
|
||||
`--delete` therefore skips what isn't the app's: `tmp/` (Passenger's `restart.txt`) and
|
||||
`.well-known/` (in case Plesk keeps certificate challenges there - *unverified* whether it does).
|
||||
The first deploy replaces the Angular files.
|
||||
|
||||
### 5. Node.js app in Plesk
|
||||
|
||||
*Websites & Domains → calendar.nachklang.art → Node.js*:
|
||||
|
||||
- Node.js version: 26 (26.13.0 on the server as of 2026-11-08; the workflow builds with the major
|
||||
from `.nvmrc`).
|
||||
- Application root: `DEPLOY_PATH` (the subdomain's own folder).
|
||||
- Document root: `DEPLOY_PATH/public` (an empty folder the workflow creates; Passenger wants one,
|
||||
the app serves its own static files from `.next/static`).
|
||||
- Application startup file: `server.js`.
|
||||
- Application mode: production.
|
||||
- **Don't** run "NPM install" there: the standalone bundle already contains its `node_modules`.
|
||||
- Optional environment variable `API_BASE_URL` (server-side fetch of the landing page's events,
|
||||
may be an internal address).
|
||||
|
||||
Port: Passenger runs `server.js` itself and takes over the port it listens on (Passenger's
|
||||
"reverse port binding" for Node apps) - *unverified* on this server; the Next server falls back
|
||||
to port 3000 if Passenger doesn't intercept.
|
||||
|
||||
## Switchover, in this order
|
||||
|
||||
1. **API first.** Merge and deploy `feature/calendar-ical-escaping-subscriptions` (still the
|
||||
existing API deploy; its Gitea workflow comes later). Backwards compatible with Angular.
|
||||
2. **Disable the Jenkins job** for Calendar_Frontend. Otherwise it runs `ng build` on the next push
|
||||
to master and fails - or worse, copies something into the old webroot.
|
||||
3. **Steps 1-4 above** (SSH, key, host key, Gitea settings).
|
||||
4. **Back up the Angular build**: download `calendar.nachklang.art/` as a ZIP in Plesk's file
|
||||
manager. The first deploy replaces those files, and this backup is the quick way back.
|
||||
5. **Merge** `feature/nextjs-rewrite` into master and watch the run under *Actions*. When the
|
||||
deploy job has finished, the folder holds the Next app but Plesk still serves it as static
|
||||
files - **the subdomain is down from here until step 6** (no `index.html` any more).
|
||||
6. **Step 5 above, right away** - switch the subdomain to the Node app. This is the moment the new
|
||||
app goes live; doing it right after the run keeps the gap to a few minutes. (Plesk might accept
|
||||
the Node.js settings before the files exist, which would allow switching first - *unverified*.)
|
||||
7. Set `DEPLOY_SMOKE_URL` and re-run the workflow (or push), so every later deploy checks that the
|
||||
page and its CSS are served.
|
||||
8. **Manual smoke test**:
|
||||
1. `/` loads styled, shows "Nächste Termine"; the Apple link opens a subscription.
|
||||
2. `/admin` signed out → admin login → back to `/admin`.
|
||||
3. List shows all calendars; an edit saves; "Abonnieren" lists links.
|
||||
4. An account without calendar permission sees "Kein Zugriff" (no redirect loop).
|
||||
5. "Abmelden" signs out and offers to sign in again.
|
||||
6. On a phone: list, "+" button, bottom sheet.
|
||||
7. An existing iCal subscription still updates (the feed URL is unchanged).
|
||||
|
||||
Things that must already be true, unchanged from Angular because the origin stays the same
|
||||
(inferred from the Angular app using the same cookie auth): the API's CORS list contains
|
||||
`https://calendar.nachklang.art` (verified in `app.factory.ts`), and so do the admin app's
|
||||
`NEXT_PUBLIC_ALLOWED_REDIRECT_ORIGINS` and the API's better-auth trusted origins.
|
||||
|
||||
## Rollback
|
||||
|
||||
Keep the last Angular build (`dist/nachklang-calendar`) for about a week and switch the subdomain
|
||||
back to it if needed. The API change is backwards compatible with the Angular app, so it can stay.
|
||||
- **Bad release:** revert the commit on master (or push the previous one); the workflow deploys it.
|
||||
- **The Node app itself doesn't work:** switch Node.js off for `calendar.nachklang.art` in Plesk, set
|
||||
the document root back to the subdomain folder, and restore the Angular backup from step 4 into
|
||||
it (or rebuild Angular from commit `f822559`: `npm ci && npx ng build`). Disable the workflow
|
||||
meanwhile, or the next push to master overwrites it again. Keep the backup about a week.
|
||||
|
||||
## Checked locally (2026-11-08)
|
||||
|
||||
- `actionlint` (in a container): no findings.
|
||||
- The deploy job's shell steps, extracted from the workflow, run against a throwaway SSH server
|
||||
(Alpine + openssh + rsync, user `nachklang`): bundle arrives owned by `nachklang`, `public/` and
|
||||
`.next/static` present, `tmp/restart.txt` touched, key removed afterwards; a second deploy
|
||||
removes stale files but keeps `tmp/`; a wrong host key aborts before anything is written.
|
||||
Against a folder set up like today's subdomain folder (Angular files, `.well-known/`, `tmp/`):
|
||||
the Angular files are replaced, `.well-known/` and `tmp/` stay.
|
||||
- Earlier (2026-09-28): `PORT=4300 node .next/standalone/server.js` serves the styled page, CSS/JS
|
||||
and the `/admin` redirect.
|
||||
|
||||
Not checked: the workflow on the real runner, Plesk's Node settings, SSH into the real server.
|
||||
Reference in new issue
Block a user