88 lines
9.5 KiB
Markdown
88 lines
9.5 KiB
Markdown
# 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 global runner `raspberry-pi-arm64` (always on; Podman), plus since 2026-10-19 a second global runner on the owner's PC (`bryan-desktop-podman`, x64). Labels per property (`linux`, `arm64`/`x64`, `podman`, machine name); `check` and `lighthouse` run on any `linux` runner, deploys only on `raspberry-pi`, and the job order makes a single runner deploy before Lighthouse. See deployment-instructions 1.1. | Q2 = A, Q3 = A, CQ5; owner 2026-10-19 |
|
|
| 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 and audit (`check`) before any deploy. **Test deploys right after `check`**, and Lighthouse (mobile + desktop) runs alongside as information. **Production waits for both `check` and Lighthouse.** Branch protection on `master` requires only `check`; Lighthouse is deliberately not a merge requirement. In CI, Lighthouse **Performance is report-only** (the Pi runner gives scores 30-40 points too low); accessibility, best practices and SEO block. Performance blocks in `pnpm check` on a PC. HTML reports are attached to every run as the `lighthouse-reports` artifact. | Q7 = A; Lighthouse CI question 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`.
|