AIDLC-documentatie voor andreaslop-site-hosting (U1 tot en met Code Generation)
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
+27
@@ -0,0 +1,27 @@
|
||||
# Pi inventory notes (input for Infrastructure Design, U2)
|
||||
|
||||
Source: relayed by session "CMS & API" from session "Pi-Main - Server" (read-only inventory, no sudo, facts not verified by this session). Full write-up in the website repo: `AndreaSlopFotografie-cms-api-foundation/aidlc-docs/features/cms-api-foundation/construction/cms-host/pi-inventory.md`. Status: UNVERIFIED INPUT, to be checked against `.gitea/workflows/deploy-scp.yaml` and confirmed by Bryan.
|
||||
|
||||
## Relayed decision (pending Bryan's confirmation in this session)
|
||||
- The test instance takes over hostname `test.andreaslop.nl`. Verify first on the Pi via the app port; Bryan then switches the route on the proxy Pi to the new port. nginx on the app Pi stays as fallback.
|
||||
|
||||
## Pattern to copy (SlpSoftware test)
|
||||
- User `gitea-workflow`; `~/apps/<name>/test/{releases,current,shared}`; `shared/env` (mode 600); `shared/wwwroot-web` symlink to `/mnt/storage1/www/html/...`.
|
||||
- systemd USER unit: `WorkingDirectory=current`, `ExecStart=dotnet ...dll`, `EnvironmentFile=shared/env`, `Restart=on-failure`, `KillSignal=SIGINT`.
|
||||
- Deploy: appleboy/drone-scp over SSH port 2224 as `gitea-workflow`; DB backup script before/after release.
|
||||
|
||||
## Network and resources
|
||||
- Free ports: 5200 (test), 5201 (production, later). ufw rule needed, allow only from proxy Pi 192.168.1.102. Taken: 5100/5101, 5150/5151, 5000, 3000, 3001, 3306, 80, 2224.
|
||||
- Proxy Pi (TLS, certbot) forwards DIRECTLY to the app port over HTTP/1.0, bypassing nginx on the app Pi. The host must therefore provide gzip, security headers, canonical 301s and a real 404 itself, and `UseHttpsRedirection` / forwarded headers must be handled as SlpSoftware does (open point 2 in requirements).
|
||||
- Pi 4, about 5.4 GiB free RAM; one more .NET process (~250-300 MB) fits. Uploads/photos on `/mnt/storage1`; releases on the SD card.
|
||||
- ARM64 builds must require runner label `arm64` or `linux-arm64` (the PC runner is x64).
|
||||
|
||||
## Database
|
||||
- MariaDB 10.11 on localhost. Convention: PascalCase DB named after the app, user = app name @localhost. Suggested by Pi-Main: `AndreaSlopTest` / `AndreaSlopCms`@localhost. SUPERSEDED by relayed naming decision: database `AndreaSlopFotografieTest`, user `AndreaSlopFotografie`@localhost (reason: the CMS is part of the website; the company is AndreaSlopFotografie). Confirmed by Bryan with approval of requirements. Existing DB `andreaslop` is WordPress: do not confuse. Bryan creates DB and user with sudo; the Pi-Main session adds the new DB to the backup script.
|
||||
|
||||
## Open design option (include both variants in Infrastructure Design)
|
||||
- Variant 1: the website CI delivers files into `wwwroot/web` directly.
|
||||
- Variant 2: `shared/wwwroot-web` symlinks to `/mnt/storage1/www/html/andreaslop-test`, the folder the existing static web deploy already writes to, so the current web deploy keeps working and the CMS host serves those files. Implication for design: the known-page set must refresh when files change in place (requirements open point 1).
|
||||
|
||||
## Manual steps for Bryan (to be finalised in the design)
|
||||
User unit, env file, database and user, ufw rule, proxy-Pi server block/route switch, Gitea secrets in the CMS repo, backup script entry. The Pi-Main session can draft exact commands once the list is final (ask via "CMS & API").
|
||||
+100
@@ -0,0 +1,100 @@
|
||||
# Requirement Verification Questions - andreaslop-site-hosting
|
||||
|
||||
Source brief: `aidlc-docs/_shared/handoffs/cms-api-foundation-brief-u1-u2.md` (decisions 1-7 in section 2 are taken and NOT re-asked).
|
||||
Please fill in your choice after each `[Answer]:` tag.
|
||||
|
||||
## Question 1: First-administrator setup flow hardening (Security)
|
||||
The brief asks us to assess whether the first-admin setup flow on the new instance can be abused by a third party before the first administrator exists (a freshly deployed test host is publicly reachable). What should the scope be?
|
||||
|
||||
- A) Assess and test the existing Identity behaviour only (no code change in Identity); document the residual risk (anyone who reaches /admin first can claim the admin account)
|
||||
- B) Assess, and additionally require a one-time setup token from configuration (env var / appsettings.local.json) on the setup endpoint, only when configured - existing hosts unchanged
|
||||
- C) Assess, and restrict the setup endpoint in the new client through configuration only (e.g. host/IP allow-list), no Identity change
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: B
|
||||
(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session)
|
||||
|
||||
## Question 2: Commit / PR flow for the two units
|
||||
How do we deliver U1 and U2 in git? (Per standing rule: I commit, but never push unless you say so.)
|
||||
|
||||
- A) One feature branch, commits per unit; no push until you ask; one PR for the whole feature after U2
|
||||
- B) One feature branch, but a PR for U1 alone after hand-back (U1 is behaviour-neutral for existing hosts), then U2 on a follow-up branch
|
||||
- C) One feature branch, commits per unit; I push and open the PR only when you explicitly say so, timing decided by you per unit
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A
|
||||
(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session)
|
||||
|
||||
## Question 3: Deployment to the test host
|
||||
May the CI/CD pipeline deploy the new client to the test host, and how is it triggered?
|
||||
|
||||
- A) Manual trigger only (workflow_dispatch); I may not run it, you trigger it
|
||||
- B) Automatic on merge to master (like the existing pipeline), plus manual trigger
|
||||
- C) I only write and verify the workflow (lint/dry run); no deploy to test is performed in this feature, you do the first deploy
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: X) Pipeline MAY deploy the new client to the TEST host (never production); the CMS session may start the test deploy itself once pipeline and Pi are ready. Bryan: "Hij mag hem uitrollen naar test. Graag zelfs dan kan het zsm getest worden, maar de CI/CD moet er nog op worden ingericht en de host ook."
|
||||
(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session)
|
||||
|
||||
## Question 4: Test-host prerequisites
|
||||
Do the test host and Gitea secrets for Andrea's instance already exist?
|
||||
|
||||
- A) Yes - host, path, SSH user and Gitea secrets exist; I only need the names (you will tell me, or I read them from the existing workflow)
|
||||
- B) Partly - the host exists but secrets/paths for the Andrea instance still have to be defined; I list what is needed in the infrastructure design
|
||||
- C) No - nothing exists yet; the design must also cover creating them (documented as manual steps for you)
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: X) Partly exists (matches B). Bryan: "De host heeft al de juiste accounts om het op te kunnen zetten, maar de inrichting op de host moet nog worden ingeregeld zoals paden, secrets, environment variables." Infrastructure design must list the remaining Pi setup (paths, secrets, env vars, database, reverse proxy) as manual steps for Bryan.
|
||||
(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session)
|
||||
|
||||
## Question 5: Admin theme scope in U2
|
||||
How far should the theme override go beyond colours, radius and font?
|
||||
|
||||
- A) Tokens only (colours, radius, font) plus logo and favicon, as in the brief; no layout or component changes
|
||||
- B) Tokens plus login/setup page branding (logo, title text) via theme assets; no layout changes
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A
|
||||
(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session)
|
||||
|
||||
## Question 6: User Stories stage
|
||||
Is a User Stories stage wanted for this infrastructure-heavy feature (personas would be: site visitor, site owner/admin, operator/developer)?
|
||||
|
||||
- A) Skip User Stories (requirements with acceptance criteria are enough)
|
||||
- B) Run a short, minimal User Stories stage
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A
|
||||
(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session)
|
||||
|
||||
## Vraag 7: Beveiligingsextensies
|
||||
Moeten de beveiligingsregels (Security Baseline) als harde vereisten worden afgedwongen voor deze feature? (De brief meldt dat je dit al hebt ingeschakeld; graag bevestigen.)
|
||||
|
||||
- A) Ja - dwing alle BEVEILIGINGSREGELS af als blokkerende vereisten
|
||||
- B) Nee - sla alle BEVEILIGINGSREGELS over
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session)
|
||||
|
||||
## Vraag 8: Property-based testing
|
||||
Moet property-based testing worden afgedwongen? (De brief meldt: gedeeltelijke modus, regels PBT-02, 03, 07, 08, 09; graag bevestigen.)
|
||||
|
||||
- A) Ja, gedeeltelijk - alleen PBT-02, 03, 07, 08, 09 (puur functies: padresolutie, canonieke vorm, beleid round-trip)
|
||||
- B) Ja, volledig - alle PBT-regels als blokkerend
|
||||
- C) Nee - sla property-based testing over
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session)
|
||||
|
||||
## Vraag 9: Operations-fase
|
||||
Moet deze feature na Construction door de Operations-fase (deployment- en monitoringsetup, production readiness)? Let op: de CI/CD-wijzigingen voor U2 zitten sowieso in de requirements; dit gaat om de aparte Operations-fase.
|
||||
|
||||
- A) Ja - voer de Operations-fase uit na Construction (deployment + monitoring setup)
|
||||
- B) Nee - stop na Build and Test (CI/CD voor de testhost wordt wel gebouwd in U2 Code Generation)
|
||||
- C) Nog niet zeker - vraag het me opnieuw na de Construction-fase
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session)
|
||||
@@ -0,0 +1,71 @@
|
||||
# Requirements - andreaslop-site-hosting
|
||||
|
||||
## 1. Intent analysis
|
||||
- **User request**: Serve Andrea's prerendered website (`AndreaSlopFotografie`, TanStack Start output) from SlpModularCms with nginx-parity behaviour, a strict CSP, and a Dutch themed admin; deploy to the **test** host. Brief: `aidlc-docs/_shared/handoffs/cms-api-foundation-brief-u1-u2.md`. Requester session: "CMS & API"; approver: Bryan.
|
||||
- **Request type**: New feature / enhancement of the shared host + new client.
|
||||
- **Scope**: Multiple components (Core hosting, Security headers, new Client project, Frontend build/theme, CI/CD).
|
||||
- **Complexity**: Complex. **Depth**: Comprehensive.
|
||||
- **Units**: U1 `core-site-hosting` (shared host, no behaviour change for existing clients), U2 `andreaslop-client`. Hand-back after each unit; **U2 starts only after the requester's "go"**.
|
||||
- **Fixed decisions**: brief section 2 (D1-D7) and Q1-Q9 in `requirement-verification-questions.md` (answers relayed by the peer session; Bryan confirms at the approval gate).
|
||||
|
||||
## 2. Unit U1 - core-site-hosting (shared host)
|
||||
|
||||
### Functional
|
||||
- **FR-U1-01 WebsiteMode.** `CmsHostOptions.WebsiteMode` enum: `SpaFallback` (default, exactly today's behaviour) and `PrerenderedPages`. `Api` and `Api.SlpSoftware` untouched; their tests unchanged.
|
||||
- **FR-U1-02 Path resolution (pure).** A total function (never throws, never leaves the website root, rejects traversal incl. encoded/backslash/NUL/over-long paths) from (request path, file-exists predicate) to `ServeFile | Redirect(301, target) | NotFound`. Rules (nginx parity, BR-HST-01..11 in the website repo):
|
||||
- `/` serves `index.html`; `/x` serves `x.html` (and `x/index.html` if present).
|
||||
- **Canonical form applies to known pages only.** nginx uses a hard-coded page list; the host derives the known-page set from the `*.html` files present in the website root. A case-insensitive variant (`/Over-Mij`, `/over-mij.html`, `/over-mij/`, `/index`, `/index.html`) gets one 301 to the lowercase, no-`.html` form; `/index*` redirects to `/`. Query string preserved. Redirect targets always come from the known-page set, never from the raw request.
|
||||
- Trailing slashes on any other path are stripped with a 301 (not for `/`). A target starting `//` or `/\` or containing control characters is treated as unknown (open-redirect guard, BR-HST-06). A path with a leading backslash is 404.
|
||||
- Hashed asset names are never lower-cased or redirected. Paths that look like files (have an extension) are served as files or 404, never fall back to a page.
|
||||
- `/404` and `/404.html` requested directly answer 404 (no redirect).
|
||||
- **FR-U1-03 Unknown path.** Serve `404.html` with status **404** (never `index.html`); plain 404 if `404.html` is missing. A directory without a page file is 404; no directory listing.
|
||||
- **FR-U1-04 Reserved prefixes.** `/admin`, `/api/v1`, `/health` are never handled by this middleware. An unknown API path remains an API 404 (today's website SPA fallback answers unknown `/api/v1` paths with `index.html`; this mode must not).
|
||||
- **FR-U1-05 Cache-Control.** Pages and other root files: `no-cache`. Files under `/assets/`: `public, max-age=31536000, immutable`.
|
||||
- **FR-U1-06 Compression.** Built-in response compression (no new dependency) for the text types in `compressibleTypes.ts` (html, js, css, svg, json, xml, txt); not for already-compressed types; `Vary: Accept-Encoding`. Website mount only (see open point 5).
|
||||
- **FR-U1-07 Indexing policy.** Setting `Website:NoIndex` (default false), bound to a validated options class. When true: `X-Robots-Tag: noindex, nofollow` on all website responses (pages, assets, 404, redirects) and `/robots.txt` answers 200 with `User-agent: *` / `Disallow: /`.
|
||||
- **FR-U1-08 StrictSite policy.** New policy name `StrictSite` in `CspPolicyCatalog` (in `KnownPolicies`, accepted by `PathPolicyRule` validation; unknown names still fail startup; `Strict` and `Relaxed` unchanged). Directives in the exact order of the site's current policy so the string matches byte for byte:
|
||||
`default-src 'self'; script-src 'self' <script origins>; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self' <connect origins>; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'`
|
||||
plus `X-Frame-Options: DENY` and `Referrer-Policy: strict-origin-when-cross-origin`. Origins come from the existing security-header configuration. An exact match is achievable (order is catalog-internal); `Strict` need not change.
|
||||
- **FR-U1-09 Other headers.** Verify and test that website responses carry `Strict-Transport-Security: max-age=31536000; includeSubDomains`, `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin` and the CSP, including on 301, 404, assets and robots.txt.
|
||||
- **FR-U1-10 Pipeline order.** Security headers before static content; compression before the website mount; website 404 handling last, after API routes; documented in `CmsHost`.
|
||||
- **FR-U1-11 Docs.** Update `WEBSITE_WORKSPACE.md` and `README.md` for the new mode and settings.
|
||||
|
||||
### Acceptance (U1)
|
||||
- Unit tests and property-based tests (partial PBT, section 5): path resolution never escapes the root, canonicalisation is idempotent, reserved prefixes never resolve, policy round trip.
|
||||
- `Api` and `Api.SlpSoftware` suites green, behaviour unchanged (regression run recorded).
|
||||
- Hand-back note (brief section 7) written and sent to "CMS & API".
|
||||
- Proxy awareness: the test site sits behind a reverse-proxy Pi that terminates TLS. Existing `UseHttpsRedirection` / forwarded-header handling must not cause redirect loops or absolute `http://` redirects; website redirects are relative (nginx `absolute_redirect off` parity). Verified in design.
|
||||
|
||||
## 3. Unit U2 - andreaslop-client
|
||||
|
||||
- **FR-U2-01 Client project** `SlpModularCms.Api.AndreaSlopFotografie` under **Clients** in the solution: thin `Program.cs` on `CmsHost`, `WebsiteMode = PrerenderedPages`, three-file appsettings (`appsettings.json`, `appsettings.{Env}.json`, uncommitted `appsettings.local.json`), own database, own dev port, `SecurityHeaders:DefaultPolicy = StrictSite` with the Umami (`https://analytics.slpsoftware.nl`) and Sentry (`https://o4511795618185216.ingest.de.sentry.io`) origins, `Website:NoIndex = true` for test.
|
||||
- **FR-U2-02 Module set** = module projects the client references (no config filter). Determine and report the minimum (Identity; is Availability required?). `Offerings` not referenced; `/api/v1/System/capabilities` must not list it.
|
||||
- **FR-U2-03 Admin theme.** `frontend/themes/andreaslop/` with CSS overriding the existing design tokens (colours, radius, font), plus logo and favicon. `VITE_THEME` selects it at build time (unset = today's look). New `VITE_DEFAULT_LANGUAGE` (`nl` for Andrea; English stays selectable). Palette: paper `#faf7f2` / `#f1ebe2` / `#e8e0d5`, ink `#232120` / `#55504b` / `#8a827a`, line `#e2dad0`, accent `#7f8b76`, accent-deep `#5f6a58` (text/buttons), accent-deeper `#475042`, sand `#d9cdbc`, error `#a4443a`. Fonts Marcellus (headings) and Jost (body) with the site's fallbacks, **self-hosted** (the admin's CSP is `font-src 'self'`). Scope per Q5: tokens + logo + favicon only, no layout or component changes. Contrast stays accessible (destructive and focus-ring colours readable on paper).
|
||||
- **FR-U2-04 CI/CD.** Build the admin per deployable client with its `VITE_THEME`, `VITE_DEFAULT_LANGUAGE`, `VITE_APP_TITLE`; publish the new host; deploy to the **test** host with the existing atomic release switch; `wwwroot/web/` stays outside the swapped release directory so the site survives every CMS deploy. The production path for `Api.SlpSoftware` is not touched.
|
||||
- **FR-U2-05 Test deploy** (Q3, relayed): the pipeline may deploy to the test host, and this session may start the test deploy itself once pipeline and Pi are ready - **test only, never production**. Bryan's go is confirmed in this session before the first deploy.
|
||||
- **FR-U2-06 Host provisioning** (Q4): the Raspberry Pi accounts exist, but paths, secrets, environment variables, database, service unit and reverse proxy are not set up yet. The infrastructure design lists every remaining step as a manual checklist for Bryan. Pi inventory comes via "CMS & API" from "Pi-Main - Server"; this session does not contact that session directly.
|
||||
- **FR-U2-07 First-admin setup token** (Q1=B): assess the existing setup flow (who can call it while no admin exists) and add an optional one-time setup token read from configuration. When configured, the setup endpoint requires it; when not configured, behaviour is unchanged for existing hosts. Constant-time comparison, never logged, covered by the same rate limiting as login. Tests: no token configured, wrong token, correct token, setup after the first admin exists (rejected). The token is a secret supplied outside the repo.
|
||||
- **FR-U2-08 Auth** otherwise unchanged (Identity module; invitations after the first admin). Login rate limiting stays.
|
||||
|
||||
### Acceptance (U2)
|
||||
Host starts on test with its own database; `/admin` shows Andrea's theme in Dutch; first-admin setup and login work; `/api/v1/System/capabilities` has no `Offerings`; `/health` is green; `Api.SlpSoftware` still builds and deploys unchanged; hand-back note written.
|
||||
|
||||
## 4. Out of scope
|
||||
Production deployment, the `Master` module for Andrea, extra roles, SSR, CMS-driven site content, a configuration-based module filter, changes to the website repo, theme editing in the admin, serving the theme from the API.
|
||||
|
||||
## 5. Cross-cutting
|
||||
- **Security Baseline**: enforced (blocking): path input validation, secure headers, no secrets in the repo, rate limiting, safe error handling, no sensitive data in logs, no new packages planned.
|
||||
- **Property-based testing**: partial mode, rules PBT-02, 03, 07, 08, 09 (pure functions: path resolution, canonical idempotence, policy round trip). Seeds are logged on failure and reproducible; tooling follows the existing test framework (decided in NFR/Code Generation).
|
||||
- **Per-unit build/test**: build and run tests after each unit's code generation.
|
||||
- **Git**: branch `feature/andreaslop-site-hosting`, commits per unit, no push until Bryan asks, one PR after U2 (Q2=A).
|
||||
- **Operations phase**: yes (Q9=A): deployment and monitoring setup and production readiness, assessed for the test environment. Production itself stays out of scope.
|
||||
- **User Stories**: skipped (Q6).
|
||||
- **Language**: documentation English, conversation Dutch.
|
||||
- **Boundaries**: website repo is read-only; no production changes; Pi contact only through "CMS & API".
|
||||
|
||||
## 6. Open points to resolve in design
|
||||
1. Where the known-page set is built (scan at startup vs. per-request lookup) and how it refreshes when a new site build is deployed.
|
||||
2. Interaction of `UseHttpsRedirection` / forwarded headers with the reverse-proxy Pi.
|
||||
3. Whether `Availability` is required next to `Identity` for the admin.
|
||||
4. Where the setup-token check lives (Identity module vs. host) without changing existing hosts.
|
||||
5. Whether compression is limited to the website mount (proposal: yes, avoids BREACH-style exposure on authenticated API responses).
|
||||
Reference in New Issue
Block a user