9.5 KiB
Deployment Plan — frontend-shell
Decisions: deployment-setup-plan.md ("Q"), deployment-clarification-questions.md ("CQ").
Overview
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.
|
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. | 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.htmlis 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 |
| 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:
- Playwright's Chromium installs and starts in the runner container (
linux-arm64). lftpwith 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.- The SSH user on the Pi may write to and empty
DEPLOY_PATH_TEST.