AIDLC-documentatie U2 (NFR, infrastructuur, code generation)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-07 01:16:34 +01:00
co-authored by Claude Sonnet 5.5
parent 88f5d20a78
commit c69ef9188e
16 changed files with 628 additions and 3 deletions
@@ -0,0 +1,50 @@
# Deployment Architecture - andreaslop-client (U2, test)
## Runtime topology
```mermaid
flowchart LR
V["Visitor / Andrea"] --> P["Proxy Pi 192.168.1.102 (TLS, certbot)"]
P -- "HTTP/1.0 + X-Forwarded-For/-Proto :5200" --> A["App Pi: ufw 5200 only from proxy"]
A --> H["andreaslopfotografie-test.service (.NET host)"]
H --> D[("MariaDB AndreaSlopFotografieTest")]
H --> W["shared/wwwroot-web -> /mnt/storage1/www/html/andreaslop-test"]
WS["Website repo deploy"] --> W
H -. "/sentry-tunnel" .-> S["Sentry (website project)"]
N["nginx on app Pi (fallback, old route)"]
classDef user fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
classDef net fill:#d6bcfa,stroke:#553c9a,stroke-width:1px,color:#000;
classDef app fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
classDef data fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
class V user;
class P,A,N net;
class H app;
class D,W,WS,S data;
```
Text alternative: visitors reach the proxy Pi, which forwards to the host on port 5200 with the client address in headers; the host reads the database and the website files (a symlinked folder that the website repo's own deploy writes), and forwards browser error reports to Sentry. The old nginx route remains as a fallback.
## Deploy sequence (CI, automatic on push to master or via the manual box, only when `ASF_TEST_DEPLOY_ENABLED=true`)
```mermaid
sequenceDiagram
box rgba(214,188,250,0.4) CI
participant G as Gitea runner
end
box rgba(99,179,237,0.4) App Pi
participant R as releases/ts
participant S as shared
participant U as systemd user unit
end
G->>G: build admin (VITE_THEME=asf, nl), publish linux-arm64
G->>R: scp release to releases/ts
G->>S: mkdir -p shared/wwwroot-web (symlink already exists)
G->>R: wwwroot/web -> ../../../shared/wwwroot-web
G->>U: ln -sfn current, restart unit
G->>G: curl https://test.andreaslop.nl/health (10 tries)
G->>R: prune to current + 1 previous
```
Text alternative: build, upload to a timestamped release, link the persistent website folder, switch `current` atomically, restart, check `/health` through the public URL, prune old releases.
## Rollback
`ln -sfn releases/<previous> current && systemctl --user restart andreaslopfotografie-test`; the previous release is always kept. Route rollback: restore the saved nginx block on the proxy Pi (see the manual steps).
@@ -0,0 +1,68 @@
# Infrastructure Design - andreaslop-client (U2, test environment only)
Status of the facts: the Pi details come from the Pi-Main inventory (unverified by this session) and are confirmed against `deploy-scp.yaml`. Items marked **(verify)** must be checked on the Pi by Bryan or the Pi-Main session before use. Production is out of scope.
## Naming convention (project decision, Bryan, relayed by "CMS & API")
The website/company is **Andrea Slop Fotografie**. New names in code, config and infrastructure use `AndreaSlopFotografie` / `andreaslopfotografie` / `andrea-slop-fotografie` or the abbreviation `ASF` / `Asf`, whichever fits the local convention (env vars and Gitea variables/secrets `ASF_...`, PascalCase identifiers `Asf...` or the full name). Never "Andrea" or "AndreaSlop" alone for NEW names. Existing names stay (domain `andreaslop.nl`, host `test.andreaslop.nl`, website repo, feature slug `andreaslop-site-hosting`, DB `AndreaSlopFotografieTest`, DB user `AndreaSlopFotografie`).
Final new names: Gitea variables `ASF_TEST_DEPLOY_ENABLED`, `DEPLOY_PATH_ASF_TEST`, `SERVICE_NAME_ASF_TEST`, `HEALTH_CHECK_URL_ASF_TEST`, `VITE_SENTRY_DSN_ASF`; jobs `publish-asf-test`, `deploy-asf-test`; theme folder `frontend/themes/asf/` with `VITE_THEME=asf`; project `SlpModularCms.Api.AndreaSlopFotografie`; Pi folder `apps/andreaslopfotografie/test`; unit `andreaslopfotografie-test.service`; env file `shared/env`; security-event label `setup_token_rejected` (generic, unchanged).
## Which Sentry project (Q3 = B)
The DSNs (`Observability__SentryDsn` and `VITE_SENTRY_DSN_ASF`) must come from the existing Sentry project of the **Andrea Slop Fotografie website**, NOT from SlpSoftware's admin project. The Umami origin (`analytics.slpsoftware.nl`) appears only in the website CSP (`StrictSite`); the host and admin set up no Umami.
## Component mapping
| Logical component | Infrastructure |
|---|---|
| `Api.AndreaSlopFotografie` host | One .NET process (linux-arm64, framework-dependent) as systemd **user** unit `andreaslopfotografie-test.service` of user `gitea-workflow`, listening on `http://0.0.0.0:5200` |
| Admin SPA (themed) | Built in CI, shipped inside the release (`wwwroot/admin`) |
| Website files | `wwwroot/web` -> `shared/wwwroot-web` -> symlink to `/mnt/storage1/www/html/andreaslop-test` (Q1 = A). The website repo's own deploy keeps writing there; no host restart needed. |
| Database | MariaDB 10.11 on the same Pi: database `AndreaSlopFotografieTest`, user `AndreaSlopFotografie`@`localhost`, rights on that database only (the host runs its own migrations at start) |
| TLS + public hostname | Proxy Pi (192.168.1.102): `test.andreaslop.nl` -> HTTP/1.0 -> app Pi port 5200; certbot stays on the proxy Pi |
| Firewall | ufw on the app Pi: port 5200/tcp only from 192.168.1.102 |
| Build + deploy | Gitea Actions: new jobs `publish-asf-test` (ubuntu-latest, `-r linux-arm64`) and `deploy-asf-test` (reuses `deploy-scp.yaml`, SSH as `gitea-workflow` with the existing `PI_MAIN_*` secrets) |
| Error reporting | Existing website Sentry project (Q3 = B) |
| Backups | Pi-Main adds `AndreaSlopFotografieTest` to the DB backup script |
## Pi layout (under the home of `gitea-workflow`, **(verify)** the absolute path)
```
apps/andreaslopfotografie/test/
releases/<yyyymmddHHMMSS>/ written by the deploy
current -> releases/<latest> switched atomically by the deploy
shared/
env mode 600, secrets, read by the unit
wwwroot-web -> /mnt/storage1/www/html/andreaslop-test
modules/ created by the deploy (empty)
```
## Environment file `shared/env` (names only; values are created by Bryan, never committed)
| Variable | Value / source |
|---|---|
| `ASPNETCORE_ENVIRONMENT` | `Production` |
| `ASPNETCORE_URLS` | `http://0.0.0.0:5200` |
| `ConnectionStrings__DefaultConnection` | `Server=localhost;Port=3306;Database=AndreaSlopFotografieTest;Uid=AndreaSlopFotografie;Pwd=<db password>` |
| `JwtSettings__Secret` | random, at least 64 characters |
| `Identity__Setup__Token` | random, at least 32 characters; remove after the first administrator exists |
| `Observability__SentryDsn` | the website's existing Sentry DSN (backend; the admin reports through the same-origin `/sentry-tunnel`) |
| `Observability__Environment` | `test` |
| `ForwardedHeaders__KnownProxies__0` | `192.168.1.102` |
| `Logging__LogLevel__SlpModularCms.Website` | `Information` (test only) |
Committed defaults (in the client's `appsettings.json`, no secrets): `SecurityHeaders` with `DefaultPolicy=StrictSite`, the site's Umami and Sentry origins, `Website:NoIndex=true` (secure default; a later production setup must set it to `false` explicitly), JWT issuer/audience, rate limiting values.
## Gitea (repository SlpModularCms) variables and secrets
| Name | Kind | Value |
|---|---|---|
| `DEPLOY_PATH_ASF_TEST` | variable | absolute path of `apps/andreaslopfotografie/test` **(verify)** |
| `SERVICE_NAME_ASF_TEST` | variable | `andreaslopfotografie-test` (**check** whether the existing SlpSoftware variable includes `.service`; use the same form) |
| `HEALTH_CHECK_URL_ASF_TEST` | variable | `https://test.andreaslop.nl/health` |
| `VITE_SENTRY_DSN_ASF` | variable | the website's Sentry DSN (a public DSN, same value as backend) |
| `ASF_TEST_DEPLOY_ENABLED` | variable | `true` ONLY when everything else is ready (the on/off switch) |
| `PI_MAIN_USERNAME`, `PI_MAIN_PASSWORD`, `PI_MAIN_PORT`, `PI_MAIN_ADDRESS` | secrets | **already exist** and are reused; they must point at the same Pi and user (`gitea-workflow`, SSH port 2224) |
Fixed in the workflow (not variables): `VITE_THEME=asf`, `VITE_DEFAULT_LANGUAGE=nl`, `VITE_APP_ENV=test`, `VITE_APP_TITLE`. No Umami for the admin.
## Sentry and CSP check (answer to the question from the website side)
The admin sends browser errors to the same-origin path `/sentry-tunnel` (`tunnel` option), and the host forwards them to the destination derived from `Observability__SentryDsn`. The admin policy `Strict` (`connect-src 'self'`) therefore needs **no** Sentry ingest origin; the website's own `StrictSite` list keeps its direct ingest host for the website's browser code. Variable names: backend `Observability__SentryDsn` (in `shared/env`), frontend build `VITE_SENTRY_DSN_ASF` (Gitea variable, passed to the build as `VITE_SENTRY_DSN`). Events from admin, host and website share one project; the environment tag (`test`) and the release/URL tell them apart.
## Existing hosts touched by the shared change (option B)
`Api`, `Api.SlpSoftware`, `Api.Slave` get the new opt-in forwarded-headers code and per-client limiters. Until `ForwardedHeaders__KnownProxies__0` is set in their environment and their proxy block passes `X-Forwarded-For`/`-Proto`, they behave as before (all callers share the proxy's address, same as today's global bucket). Enabling it for SlpSoftware test/production is an optional separate step in the manual list.
@@ -0,0 +1,39 @@
# Manual steps for Bryan - Andrea Slop Fotografie (ASF) test host (ordered, complete)
Scope: test environment only. Nothing here touches production. Commands are drafted by the Pi-Main session (via "CMS & API") from this list; this list says WHAT and in WHICH ORDER. Items marked **(verify)** are facts from the inventory that were not verified by the author.
Legend: **[Pi]** app Pi, **[Proxy]** proxy Pi 192.168.1.102, **[Gitea]** the CMS repository settings, **[Code]** needs the code on Gitea.
## Phase A - Prepare (nothing is live yet; the old nginx route keeps serving)
1. **[Pi] Verify prerequisites**: user `gitea-workflow` exists and has lingering enabled for user units (`loginctl enable-linger gitea-workflow`) (verify); `dotnet` runtime 10 is installed and its path is known (verify); port 5200 is free; the folder `/mnt/storage1/www/html/andreaslop-test` exists and `gitea-workflow` can read it (group/mode; the SlpSoftware setup needed a cross-account permission fix of the same kind) (verify).
2. **[Pi] Database** (sudo): create database `AndreaSlopFotografieTest` (utf8mb4) and user `AndreaSlopFotografie`@`localhost` with a strong password; grant all privileges on that database only. Note the password for step 4. Do not confuse with the WordPress database `andreaslop`.
3. **[Pi] Directories** as `gitea-workflow`: `apps/andreaslopfotografie/test/{releases,shared}`. Create the symlink `shared/wwwroot-web` -> `/mnt/storage1/www/html/andreaslop-test`. (Variant B, only if you choose it later: skip the symlink; the website pipeline then copies into `shared/wwwroot-web` itself.)
4. **[Pi] `shared/env`** (mode 600, owner `gitea-workflow`) with the variables from `infrastructure-design.md`: `ASPNETCORE_ENVIRONMENT`, `ASPNETCORE_URLS`, `ConnectionStrings__DefaultConnection`, `JwtSettings__Secret`, `Identity__Setup__Token`, `Observability__SentryDsn`, `Observability__Environment`, `ForwardedHeaders__KnownProxies__0`, `Logging__LogLevel__SlpModularCms.Website`. Generate the JWT secret (64+ chars) and the setup token (32+ chars) randomly; keep the token for step 17.
5. **[Pi] systemd user unit** `~/.config/systemd/user/andreaslopfotografie-test.service`: `WorkingDirectory=<deploy path>/current`, `EnvironmentFile=<deploy path>/shared/env`, `ExecStart=<dotnet path> SlpModularCms.Api.AndreaSlopFotografie.dll`, `Restart=on-failure`, `KillSignal=SIGINT`, `WantedBy=default.target`. Run `systemctl --user daemon-reload` and `systemctl --user enable` (do **not** start yet: `current` does not exist until the first deploy).
6. **[Pi] Firewall**: allow 5200/tcp only from 192.168.1.102; verify with `ufw status`.
7. **[Pi, Pi-Main] Backup**: add `AndreaSlopFotografieTest` to the DB backup script.
8. **[Gitea] Variables** (repository SlpModularCms): `DEPLOY_PATH_ASF_TEST`, `SERVICE_NAME_ASF_TEST` (same form as the SlpSoftware one), `HEALTH_CHECK_URL_ASF_TEST=https://test.andreaslop.nl/health`, `VITE_SENTRY_DSN_ASF` (the website's Sentry DSN). The existing secrets `PI_MAIN_*` are reused: confirm they point at the same Pi and user. **Do NOT set `ASF_TEST_DEPLOY_ENABLED` yet.** Until it is `true` the ASF jobs are skipped and the pipeline stays as it is.
9. **[Code] Make the code available to Gitea**: this feature's branch must be pushed (or merged into master) before any deploy can run. I do not push; tell me when you want that. A merge to master with the switch off changes nothing for Andrea.
## Phase B - Cut over (this causes the short test downtime you accepted)
10. **[Proxy] Save the current server block** for `test.andreaslop.nl` (copy the file; this is the revert point).
11. **[Proxy] Switch the route**: the block for `test.andreaslop.nl` (website repo copy: `web/deploy/nginx/test.andreaslop.nl.proxy.conf`, generated by `web/config/serverConfig.ts`) already sets `Host`, `X-Forwarded-For` (`$proxy_add_x_forwarded_for`), `X-Forwarded-Proto` (`$scheme`) and `X-Real-IP`. **Verify** these three forwarded headers are present in the live block (grep), then change only the target: `proxy_pass http://192.168.1.103;` (port 80, nginx fallback) -> `proxy_pass http://192.168.1.103:5200;`. Keep the certbot TLS settings. Test the config, reload nginx. Until the first deploy the site answers 502/503 (expected). The generator in the website repo is updated in U3 so the repo copy matches.
12. **[Gitea] Set `ASF_TEST_DEPLOY_ENABLED=true`.**
13. **[Gitea/Code] Run the first deploy**: push to master, or start "Continuous Integration" manually with the box "Deploy ASF test" ticked. Watch the job: build admin, publish, upload, link, switch, restart, `/health` check on the public URL, prune.
## Phase C - Verify (can be done together with this session)
14. `curl -I https://test.andreaslop.nl/` -> 200 with CSP, HSTS, `X-Robots-Tag: noindex, nofollow`; `/over-mij` (or any page) 200; `/Over-Mij` -> one 301; an unknown path -> 404 with the 404 page; `/robots.txt` -> `Disallow: /`.
15. `https://test.andreaslop.nl/health` -> healthy; `/api/v1/System/capabilities` -> no `Offerings`.
16. `/admin/`: Andrea's theme, Dutch; the setup page asks for the setup token.
17. Create the first administrator with the setup token. Afterwards **remove `Identity__Setup__Token` from `shared/env`** and restart the unit (the setup endpoint is closed once initialised; removing the token is hygiene).
18. Report what you see for the forwarded headers (visitor address in the logs/limiter rather than 192.168.1.102) and optionally time a page request on the Pi; both are asked for in the hand-back.
## Rollback
- **Release**: `ln -sfn releases/<previous> current` and `systemctl --user restart andreaslopfotografie-test`.
- **Route**: restore the saved nginx block on the proxy Pi (step 10) and reload; the old nginx fallback on the app Pi serves the test site again.
- **Switch off CI**: set `ASF_TEST_DEPLOY_ENABLED` to anything but `true`.
## Optional, separate (existing hosts; only if you want per-visitor rate limits there too)
- **SlpSoftware test**: add `ForwardedHeaders__KnownProxies__0=192.168.1.102` to its `shared/env`, make sure its proxy-Pi block sets `X-Forwarded-For`/`-Proto`, restart the unit after the next deploy of the new code.
- **SlpSoftware production and other hosts**: the same two things, later, when you decide. Until then they behave exactly as before.
- Production Andrea: out of scope for this feature (when it comes: `Website__NoIndex=false`, its own database/port 5201/route).