Adds Gitea Actions CI/CD for test and production
The pipeline runs lint, format, tests, build, dependency audit and Lighthouse (mobile and desktop, Playwright Chromium on the arm64 runner) on every pull request, push to master and manual run. Pushes to master deploy to test automatically, and any branch can be deployed to test manually. Test is a Raspberry Pi with nginx next to the current WordPress site; the deploy refuses folders containing WordPress. Production deploys are manual and only from release/* branches, over FTP with TLS to the IIS webhost. The IIS web.config and both nginx configs are generated from the same security header list as the Vite servers, with a test that fails when the generated files drift. Adds .gitattributes for LF line endings and pins pnpm through packageManager. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,124 @@
|
||||
# Deployment Instructions — frontend-shell
|
||||
|
||||
Pipeline: [`.gitea/workflows/continuous_integration.yaml`](../../../../../.gitea/workflows/continuous_integration.yaml).
|
||||
|
||||
## 1. One-time setup
|
||||
|
||||
### 1.1 Gitea repository settings
|
||||
In Gitea, under **Repository → Settings → Actions**:
|
||||
|
||||
**Secrets** (encrypted):
|
||||
|
||||
| Name | Value |
|
||||
|---|---|
|
||||
| `PI_MAIN_ADDRESS` | Address of the Pi as reachable from the runner (same as in your other projects) |
|
||||
| `PI_MAIN_PORT` | SSH port |
|
||||
| `PI_MAIN_USERNAME` | SSH user |
|
||||
| `PI_MAIN_PASSWORD` | SSH password (see 1.4 for switching to a key) |
|
||||
| `FTP_HOST` | Domain or A-record IP of the hosting space (control panel) |
|
||||
| `FTP_USERNAME` | FTP account **including** the FTP prefix |
|
||||
| `FTP_PASSWORD` | Password of that FTP account |
|
||||
|
||||
**Variables** (not secret):
|
||||
|
||||
| Name | Example | Required |
|
||||
|---|---|---|
|
||||
| `DEPLOY_PATH_TEST` | `/var/www/html/andreaslop-test` | yes |
|
||||
| `HEALTH_CHECK_URL_TEST` | `https://test.andreaslop.nl/` | no; without it the post-deploy check is skipped |
|
||||
| `HEALTH_CHECK_URL_PRODUCTION` | `https://andreaslop.nl/` | no; set it only once the DNS points to the new host |
|
||||
| `FTP_REMOTE_DIR` | `wwwroot` | no; default `wwwroot` |
|
||||
|
||||
Check that Actions is enabled for the repository. The global runner `raspberry-pi-arm64` picks up `runs-on: ubuntu-latest`.
|
||||
|
||||
### 1.2 Test server (Raspberry Pi with nginx)
|
||||
The current WordPress site runs on the same Pi. The test site gets its **own folder** and its **own nginx block**, and touches nothing of WordPress.
|
||||
|
||||
1. Create a separate folder, **not** inside the WordPress folder:
|
||||
```bash
|
||||
sudo mkdir -p /var/www/html/andreaslop-test
|
||||
sudo chown <ssh-user> /var/www/html/andreaslop-test
|
||||
```
|
||||
Every deploy empties this folder first. The pipeline refuses a folder with `wp-config.php` or `wp-content` in it.
|
||||
2. Copy [`web/deploy/nginx/andreaslop-test.conf`](../../../../../web/deploy/nginx/andreaslop-test.conf) to `/etc/nginx/conf.d/andreaslop-test.conf`. nginx loads everything in `conf.d/` automatically, so no symlink is needed. Adjust `server_name` and `root` if needed.
|
||||
```bash
|
||||
sudo cp web/deploy/nginx/andreaslop-test.conf /etc/nginx/conf.d/andreaslop-test.conf
|
||||
```
|
||||
After `pnpm server-config` changes the file, copy it again (manual step; see "Test vs Production" in the deployment plan).
|
||||
- The block answers only the test hostname, and never acts as `default_server`, so WordPress keeps getting its own requests.
|
||||
- Do not change the WordPress server block.
|
||||
3. Run `sudo nginx -t && sudo systemctl reload nginx`.
|
||||
4. On the reverse-proxy Pi, install the HTTP-only proxy config [`web/deploy/nginx/test.andreaslop.nl.proxy.conf`](../../../../../web/deploy/nginx/test.andreaslop.nl.proxy.conf). It forwards the test hostname to the hosting Pi.
|
||||
- The **`Host` header is required**, and the file sets it. The hosting Pi uses it to choose between the WordPress block and the test block; without it the request lands on the default block (WordPress).
|
||||
- The hosting Pi's address (`192.168.1.103`) is set in `config/serverConfig.ts`. Change it there and run `pnpm server-config`, never in the generated file.
|
||||
```bash
|
||||
sudo cp test.andreaslop.nl.proxy.conf /etc/nginx/conf.d/test.andreaslop.nl.conf
|
||||
sudo nginx -t && sudo systemctl reload nginx
|
||||
```
|
||||
Then let certbot add TLS and the HTTP→HTTPS redirect. certbot edits this file on the proxy:
|
||||
```bash
|
||||
sudo certbot --nginx -d test.andreaslop.nl
|
||||
```
|
||||
- **Only copy the file once.** Copying it again overwrites certbot's HTTPS changes. If the repository version ever changes, copy it and run `certbot --nginx -d test.andreaslop.nl` again.
|
||||
Do **not** add the security headers or `X-Robots-Tag` on the proxy too. The hosting Pi already sets them, and setting them twice makes browsers see duplicate headers.
|
||||
5. Create a DNS record for the test hostname that points to your proxy.
|
||||
|
||||
The folder is empty until the first deploy. Run a deploy before testing.
|
||||
|
||||
### 1.3 Production (MijnHostingPartner)
|
||||
1. In the control panel, create an FTP account for the website. Use its full username, prefix included, in `FTP_USERNAME`.
|
||||
2. Check that TLS is available for FTP. If it isn't, open a ticket (per the hoster's knowledge base); the pipeline refuses plain FTP.
|
||||
3. Set up the domain `andreaslop.nl` in the package, but **do not change the DNS yet** (D12).
|
||||
|
||||
### 1.4 Later: SSH key instead of a password (recommended)
|
||||
Create a deploy key, put the public key in `~/.ssh/authorized_keys` on the Pi, and store the private key as the secret `PI_MAIN_SSH_KEY`. In the `deploy-test` job, replace `sshpass -e` with `ssh -i`. This is the same change as in your other projects.
|
||||
|
||||
### 1.5 Line endings (once, after pulling this change)
|
||||
`.gitattributes` makes Git use LF. Refresh your working copy once:
|
||||
```bash
|
||||
git rm --cached -r -q . && git reset --hard
|
||||
```
|
||||
**Warning**: this throws away uncommitted changes. Commit or stash first.
|
||||
|
||||
## 2. Day to day
|
||||
|
||||
### Feature work
|
||||
1. `git switch -c feature/<name>` from `master`, work, push.
|
||||
2. Open a pull request. CI runs: lint, format, tests, build, audit and Lighthouse.
|
||||
3. Want to see it on test before merging? Go to **Actions → Continuous Integration → Run workflow**, pick your branch, tick **Deploy to Test**.
|
||||
4. Merge the PR. `master` is deployed to test automatically.
|
||||
|
||||
### Release to production
|
||||
1. Cut a release branch from `master`: `git switch -c release/1.0 master`, then `git push -u origin release/1.0`.
|
||||
2. Check it on test: run the workflow on `release/1.0` with **Deploy to Test**.
|
||||
3. Deploy: run the workflow on `release/1.0` with **Deploy to Production**. The job only runs on `release/*` branches.
|
||||
4. Afterwards, merge `release/1.0` back into `master` (PR) and tag the merge commit:
|
||||
```bash
|
||||
git switch master && git pull
|
||||
git tag -a v1.0.0 -m "Release 1.0.0" && git push origin v1.0.0
|
||||
```
|
||||
5. A fix on a release goes to the release branch first, and is deployed and merged back the same way (tag `v1.0.1`).
|
||||
|
||||
### Go-live (once)
|
||||
1. **Dress rehearsal on the production host.** This is the only place IIS and FTPS are tested; test runs nginx (see "Test vs Production" in the deployment plan).
|
||||
- Run a production deploy.
|
||||
- Without changing DNS, open the new host via a temporary `hosts` entry (`<A-record IP> andreaslop.nl`) or the hoster's preview URL.
|
||||
- Check:
|
||||
- the home page and a deep link (`/portfolio`)
|
||||
- an unknown URL (the 404 page)
|
||||
- the five security headers (`curl -sI`)
|
||||
- that HTTP redirects to HTTPS
|
||||
- Remove the `hosts` entry afterwards.
|
||||
2. Switch the DNS of `andreaslop.nl` (and `www`) to the new host, and make sure HTTPS is active.
|
||||
3. Set `HEALTH_CHECK_URL_PRODUCTION` so every deploy is checked from then on.
|
||||
4. Verify the live headers: `curl -sI https://andreaslop.nl/` must show all five security headers.
|
||||
|
||||
## 3. If something fails
|
||||
|
||||
| Symptom | Likely cause | Fix |
|
||||
|---|---|---|
|
||||
| `Install Chromium` fails | Playwright cannot install its dependencies in the runner image | Look at the log for the missing package. As a fallback, run Lighthouse locally (`pnpm lighthouse`) and make the CI job optional; report it so we can fix it properly. |
|
||||
| Lighthouse: "Chrome could not be started" | Sandbox | `LIGHTHOUSE_CHROME_FLAGS` must contain `--no-sandbox` (already set). |
|
||||
| `Format` fails only in CI | Line endings | See 1.5. |
|
||||
| `sshpass`: Permission denied | Wrong secret, or special characters | Secrets go via `env:` (already so); check the values. |
|
||||
| `lftp`: certificate verification failed | Hostname does not match the hoster's certificate | Use the hostname from the control panel in `FTP_HOST`, not the IP. |
|
||||
| Health check fails, page is 404 on deep links | SPA fallback missing | Production: `web.config` not uploaded or URL Rewrite off. Test: nginx config not active. |
|
||||
@@ -0,0 +1,87 @@
|
||||
# Deployment Plan — frontend-shell
|
||||
|
||||
Decisions: [deployment-setup-plan.md](../plans/deployment-setup-plan.md) ("Q"), [deployment-clarification-questions.md](../plans/deployment-clarification-questions.md) ("CQ").
|
||||
|
||||
## Overview
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Feature["feature/* branch"] -->|"pull request"| CI1["CI: check + Lighthouse"]
|
||||
Feature -->|"manual, Deploy to Test"| Test["Test: Raspberry Pi nginx"]
|
||||
CI1 -->|"merge"| Master["master"]
|
||||
Master -->|"automatic"| Test
|
||||
Master -->|"branch off"| Release["release/x.y"]
|
||||
Release -->|"manual, Deploy to Production"| Prod["Production: IIS webhost via FTPS"]
|
||||
Release -->|"merge back + tag vX.Y.Z"| Master
|
||||
|
||||
classDef branch fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
classDef ci fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef env fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
|
||||
class Feature,Master,Release branch;
|
||||
class CI1 ci;
|
||||
class Test,Prod env;
|
||||
```
|
||||
|
||||
Text alternative: feature branches go through a pull request with CI into master; master deploys to test automatically and any branch can be deployed to test manually; release branches are cut from master, deployed to production manually, then merged back into master and tagged.
|
||||
|
||||
## Decisions
|
||||
|
||||
| # | Decision | Source |
|
||||
|---|---|---|
|
||||
| D1 | **CI**: Gitea Actions on the existing global runner `raspberry-pi-arm64` (labels `linux-arm64`, `ubuntu-latest`; Podman). | Q2 = A, Q3 = A, CQ5 |
|
||||
| D2 | **Branching**: `master` + short-lived `feature/*` + `release/*`, no `develop` (trunk-based with release branches). Releases are merged back into `master` and tagged `vX.Y.Z` there. | CQ1 |
|
||||
| D3 | **Environments**: test and production. | Q5 = B |
|
||||
| D4 | **Test deploy**: automatically on every push to `master` (incl. a merged PR), and manually from any branch with "Deploy to Test", for example to try a branch before merging. | Q6 = B, CQ1 |
|
||||
| D5 | **Production deploy**: manual only ("Deploy to Production"), and only from a `release/*` branch; the workflow refuses other branches. | Q6 = B, CQ1 |
|
||||
| D6 | **Quality gate**: every run does lint, format, tests, build, audit and Lighthouse (mobile + desktop) before any deploy job can start. | Q7 = A |
|
||||
| D7 | **Chrome for Lighthouse**: Playwright's Chromium (supports linux-arm64), installed in the job with a pinned Playwright version. Not the browser on the host: jobs run in containers and cannot see it. | CQ5 |
|
||||
| D8 | **Test target**: Raspberry Pi with nginx behind the reverse-proxy Pi, **next to the current WordPress site**. Deploy over SSH (`sshpass` + `scp`, same secrets as your other projects). Simple: empty the test folder, then copy the new build in; no old versions are kept. The step refuses an empty path, `/`, or a folder containing WordPress (`wp-config.php` / `wp-content`). The nginx block has its own `server_name` and never `default_server`. | CQ4 = B; owner: simpler than other apps, must not conflict with WordPress |
|
||||
| D9 | **Test is never indexed**: `X-Robots-Tag: noindex, nofollow` and a `robots.txt` that disallows everything. | Derived |
|
||||
| D10 | **Production target**: MijnHostingPartner ASP.NET Core 10 package (Windows/IIS). Upload with `lftp` over FTP with TLS (forced) to `wwwroot`. Order: all files except `index.html`, then `index.html`, then delete stale files. | Q4, CQ3 = B |
|
||||
| D11 | **Server config from one source**: generated with `pnpm server-config`, and a test fails if the files drift from the generator. <ul><li>`web/deploy/iis/web.config` (production) and `web/deploy/nginx/andreaslop-test.conf` (test hosting Pi) carry the headers from `config/securityHeaders.ts`.</li><li>`web/deploy/nginx/test.andreaslop.nl.proxy.conf` (reverse-proxy Pi) is HTTP only, sets no headers, and certbot adds HTTPS to it.</li></ul> | NFR-SEC-01/02 |
|
||||
| D12 | **Go-live**: the production pipeline is ready, but the DNS of `andreaslop.nl` keeps pointing to the current host until the pages have content. Deploying to the new host does not affect the live site until the DNS switch. | CQ2 = A |
|
||||
| D13 | **Rollback**: redeploy a previous version through the pipeline, the same way on test and production. See [rollback-plan.md](rollback-plan.md). | Q8 = B |
|
||||
| D14 | **Line endings**: `.gitattributes` with `eol=lf`, so the runner and every machine see the same files and Prettier passes. | Derived |
|
||||
| D15 | **Versions pinned**: Node 24 in CI; pnpm via `packageManager` (`pnpm@12.11.2`, also pinned in the lockfile); Playwright 1.55.0. | SECURITY-10 |
|
||||
|
||||
## Test vs Production
|
||||
|
||||
A subdomain counts as an extra website in the hosting package (only one is included), so test stays on the Raspberry Pi. The goal of test is that **the site can be tested**. Deployment may differ because the environments differ. The rule:
|
||||
- Nothing happens on test that cannot happen on production, unless it is listed here.
|
||||
- For every difference it is stated whether it is automatic or manual.
|
||||
|
||||
### Identical on both
|
||||
- **Build**: one artifact per run, deployed unchanged to both environments.
|
||||
- **Security headers and SPA fallback**: generated from the same source (`config/securityHeaders.ts`) into the nginx and IIS config; a test fails if they drift.
|
||||
- **Unknown URLs**: return the app (HTTP 200), which shows the 404 page.
|
||||
- **Quality gate**: lint, format, tests, build, audit and Lighthouse before every deploy.
|
||||
- **Caching**: `index.html` is never cached; files in `/assets` (hashed names) are cached for a year.
|
||||
|
||||
### Differences
|
||||
|
||||
| Aspect | Test (Raspberry Pi, nginx) | Production (webhost, IIS) | Automatic / manual |
|
||||
|---|---|---|---|
|
||||
| Deploy trigger | Automatic on push to `master`; manual from any branch | Manual only, from `release/*` | By design |
|
||||
| Transport | SSH/scp | FTP with TLS (`lftp`) | Both automatic in the pipeline |
|
||||
| Upload method | Empty the test folder, then copy the build (a few seconds offline; fine for test) | Upload over the existing files: first all files except `index.html`, then `index.html`, then delete stale files (no offline moment) | Both automatic |
|
||||
| Rollback | Redeploy a previous version through the pipeline (manual start) | Same: redeploy a previous version through the pipeline (manual start) | Identical route; see [rollback-plan.md](rollback-plan.md) |
|
||||
| Neighbours on the server | The current WordPress site (andreaslop.nl) runs on the same Pi; the test site has its own folder and nginx block | The hosting package has only this site | Guard in the deploy step (automatic); nginx block installed by hand once |
|
||||
| Server config | `deploy/nginx/andreaslop-test.conf` on the hosting Pi and `deploy/nginx/test.andreaslop.nl.proxy.conf` on the proxy Pi (then certbot), each installed **once by hand** | `deploy/iis/web.config`, uploaded **automatically** with every deploy | Re-install the nginx config by hand after `pnpm server-config` changes it |
|
||||
| Indexing | `noindex` header + `robots.txt` that blocks everything (test only) | Normal: `robots.txt` and `sitemap.xml` from the build | Automatic |
|
||||
| HTTPS | Terminated on the reverse-proxy Pi; redirect is the proxy's job | `web.config` redirects HTTP to HTTPS; certificate from the hoster | Test: proxy config, manual |
|
||||
| Compression | nginx gzip settings of the Pi | Whatever IIS at the hoster does | Not managed by this project; may make Lighthouse scores differ slightly |
|
||||
| Post-deploy check | `HEALTH_CHECK_URL_TEST` | `HEALTH_CHECK_URL_PRODUCTION` (set after go-live) | Automatic once the variable is set |
|
||||
|
||||
### Covering the IIS-specific risk
|
||||
Only production runs IIS and FTPS. A mistake in `web.config` or in the upload would therefore first show up there. Until go-live the DNS still points to the old host, so production can serve as a **dress rehearsal**: deploy, then test the new host before switching DNS (deployment-instructions.md, Go-live step 1). After go-live, every release follows the same route, and the post-deploy check verifies reachability and headers.
|
||||
|
||||
## Later: when the .NET API arrives
|
||||
- The hosting package has one website. The API (from its own project) will then serve this site as static files. That replaces `web.config`: the API sets the same headers (from the same list) and the SPA fallback in ASP.NET Core.
|
||||
- **Database migrations**: run them in the pipeline before the new API goes live. Keep them backward compatible (expand/contract) and fix problems by rolling forward. Take a backup before each production migration. See the rollback plan.
|
||||
|
||||
## Not verified yet (needs the first real runs)
|
||||
These depend on the runner and the hoster and could not be tested from this machine:
|
||||
1. Playwright's Chromium installs and starts in the runner container (`linux-arm64`).
|
||||
2. `lftp` with forced TLS is accepted by the hoster's certificate. If the certificate does not match the hostname, the fix is to connect with the hostname from the hoster's control panel, not to turn verification off.
|
||||
3. The SSH user on the Pi may write to and empty `DEPLOY_PATH_TEST`.
|
||||
@@ -0,0 +1,31 @@
|
||||
# Rollback Plan — frontend-shell
|
||||
|
||||
Principle (Q8 = B): roll back by **deploying a previous version through the pipeline**. The site is static: there is no state or database to undo.
|
||||
|
||||
## Test environment
|
||||
|
||||
Old versions are not kept on test (keeping it simple). To go back, run the workflow on the branch, commit or tag you want, with **Deploy to Test**. This is the same route as production, so a rollback on test is also a rehearsal for production.
|
||||
|
||||
## Production
|
||||
|
||||
1. **Choose the version.** That is the previous tag (for example `v1.0.0`) or the release branch from before the faulty change.
|
||||
2. **Deploy it.** If the release branch still exists at that version, run the workflow on it with **Deploy to Production**. Otherwise create a branch from the tag first:
|
||||
```bash
|
||||
git switch -c release/1.0-rollback v1.0.0 && git push -u origin release/1.0-rollback
|
||||
```
|
||||
Then deploy that branch. Production deploys are only allowed from `release/*`, which is why the branch is needed.
|
||||
3. **Check the result.** The pipeline's post-deploy check verifies reachability and the CSP header. Also open a deep link (for example `/portfolio`) and the home page.
|
||||
4. **Fix forward.** Fix the problem on the release branch and deploy again as a new patch version.
|
||||
|
||||
**Emergency (pipeline unavailable):** run `pnpm build` locally from the tag, copy `web/deploy/iis/web.config` into `dist/`, and upload `dist/` with FileZilla to `wwwroot`. Use "FTP over explicit TLS", and upload `index.html` last.
|
||||
|
||||
## Before go-live
|
||||
As long as the DNS points to the current host (D12), a broken production deploy affects no visitors. Fix it and deploy again.
|
||||
|
||||
## Later: with the .NET API and a database
|
||||
- **Code**: roll back the same way, by deploying the previous version.
|
||||
- **Database**: do **not** roll back with "down" migrations, because they can destroy data. Instead:
|
||||
- Make migrations backward compatible (expand/contract), so the previous API version still works on the new schema.
|
||||
- Back up the database (or export it; the package allows 50 MB) before every production migration. The pipeline can do this as a step.
|
||||
- Fix errors in data or schema with a new migration (roll forward).
|
||||
- **Restore from backup** only as a last resort, when data was damaged.
|
||||
Reference in New Issue
Block a user