Files
AndreaSlopFotografie/aidlc-docs/features/frontend-shell/operations/deployment/deployment-plan.md
T
2026-10-19 14:58:56 +02:00

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.
  • web/deploy/iis/web.config (production) and web/deploy/nginx/andreaslop-test.conf (test hosting Pi) carry the headers from config/securityHeaders.ts.
  • web/deploy/nginx/test.andreaslop.nl.proxy.conf (reverse-proxy Pi) is HTTP only, sets no headers, and certbot adds HTTPS to it.
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.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
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.