Files
slp-modular-cms/docs/deploy-asf-productie.md
T
SluijsensandClaude Sonnet 5.5 19cd86a341
Continuous Integration / config-sls (pull_request) Successful in 6s
Continuous Integration / changes (pull_request) Successful in 11s
Continuous Integration / backend-build (pull_request) Skipped
Continuous Integration / compile-sites (pull_request) Skipped
Continuous Integration / backend-test (pull_request) Skipped
Continuous Integration / vulnerability-scan (pull_request) Skipped
Continuous Integration / frontend-prepare (pull_request) Skipped
Continuous Integration / frontend-build (pull_request) Skipped
Continuous Integration / frontend-test (pull_request) Skipped
Continuous Integration / frontend-lint (pull_request) Skipped
Continuous Integration / publish-sls-test (pull_request) Skipped
Continuous Integration / publish-sls-production (pull_request) Skipped
Continuous Integration / deploy-sls-test (pull_request) Skipped
Continuous Integration / deploy-sls-production (pull_request) Skipped
Continuous Integration / publish-asf-test (pull_request) Skipped
Continuous Integration / publish-asf-production (pull_request) Skipped
Continuous Integration / deploy-asf-production (pull_request) Skipped
Continuous Integration / smoke-sls-test (pull_request) Skipped
Continuous Integration / config-asf (pull_request) Successful in 12s
Continuous Integration / deploy-asf-test (pull_request) Skipped
Continuous Integration / smoke-asf-test (pull_request) Skipped
Docs: verlopen certificaatketen van de FTPS-server; controle weer aan zodra opgelost
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-19 01:40:25 +01:00

112 lines
11 KiB
Markdown

# ASF productie op IIS: bouwen, uploaden, eerste uitrol, terugdraaien
Status: de pijplijn is gebouwd maar staat **uit**. Er is niets naar productie gezet; dat gebeurt alleen met Bryans expliciete go. Voor wie: Bryan (eerste uitrol) en wie de pijplijn beheert. De configuratiesleutels, de `web.config` en de database staan in `aidlc-docs/features/andreaslop-site-hosting/asf-iis-production-config.md`; dit document gaat over de uitrol zelf.
## 1. Wat er is
| Onderdeel | Waar | Doet |
|---|---|---|
| Job `publish-asf-production` | `.gitea/workflows/continuous_integration.yaml` | Bouwt de ASF-host self-contained voor win-x64 (de runtime zit erbij; alleen de IIS-module uit de Hosting Bundle is op de server nodig), met de admin-frontend (ASF-thema, Nederlands) en het `web.config`-sjabloon. Bewaart het resultaat 30 dagen als pijplijnartefact `app-asf-production-win-x64`. |
| `deploy/asf-iis/web.config` | repo | Het sjabloon: handler inprocess, stdout-log aan voor de eerste start, uploadlimiet 30 MB, requestFiltering (configbestanden en programmabestanden nooit rechtstreeks downloadbaar), `ASPNETCORE_ENVIRONMENT=Production`, de hosterstandaard. Geen instellingen, geen geheimen. |
| `scripts/check-asf-publish.sh` | repo | Controle van het artefact; laat de job falen als er `appsettings.Production.json`, `uploads/`, `logs/`, `wwwroot/web`, andere `appsettings.*.json`, sleutel- of certificaatbestanden in zitten, of als het sjabloon-`web.config`, het win-x64-Magick-bestand of de admin ontbreekt, of als de `web.config` iets geheimachtigs bevat. |
| Job `deploy-asf-production` | idem | Uploadt het artefact via FTPS met `scripts/deploy-asf-iis-ftps.sh`. **Standaard uit** (zie 2). |
| `scripts/deploy-asf-iis-ftps.sh` | repo | De upload: expliciete FTPS (AUTH TLS), TLS afgedwongen voor besturing en data, certificaat gecontroleerd, passief, wachtwoord alleen via `LFTP_PASSWORD`; dezelfde stijl als de website-upload van het ASF-project. |
Een push naar `master` of een pull request bouwt of uploadt hier **nooit** iets.
## 2. Wanneer de upload draait (drie sloten)
`deploy-asf-production` draait alleen als **alle drie** gelden:
1. een handmatige run (`workflow_dispatch`) met **`deploy_asf_production`** aangevinkt;
2. die run staat op een branch **`release/*`**;
3. de Gitea-variabele **`ASF_PROD_DEPLOY_ENABLED`** is `true` (standaard niet aanwezig; pas zetten op Bryans go en na afloop weer weghalen).
Alleen bouwen (zonder upload): dispatch met **`build_asf_production`** aangevinkt, op elke branch. Zo is de zip te controleren zonder dat er iets naar een server gaat.
Instellingen (de variabelen en secrets bestaan al in de CMS-repo; het hosterpad staat nu nog op een plaatshouder):
| Naam | Soort | Betekenis |
|---|---|---|
| `ASF_PROD_HOST_ADDRESS`, `ASF_PROD_HOST_PORT` (optioneel), `ASF_PROD_HOST_USERNAME`, `ASF_PROD_HOST_PASSWORD` | secrets | FTPS-account van de hoster. |
| `ASF_PROD_DEPLOY_PATH` | variabele | De **hostmap** (de map met de `.exe`, de `web.config` en de `wwwroot`), relatief aan de FTP-thuismap. Alleen `A-Za-z0-9._/-`. **Niet** `wwwroot/web`. Nu `wwwroot` als plaatshouder: leg dit met Bryan vast zodra het echte hosterpad bekend is. Is de IIS-sitemap de `wwwroot` van het account, dan wordt de website-map `<account>/wwwroot/wwwroot/web`; leg dat bij de eerste uitrol vast. |
| `ASF_PROD_HEALTH_URL` | variabele | `https://andreaslop.nl/health` (health-check na de upload). |
| `ASF_PROD_SENTRY_DSN` | variabele (optioneel) | DSN voor de admin-frontend. |
| `ASF_PROD_DEPLOY_ENABLED` | variabele | Het derde slot, zie boven. |
## 3. Wat de upload doet en nooit doet
Volgorde (`scripts/deploy-asf-iis-ftps.sh`):
1. Verbinding en doelmap controleren.
2. `app_offline.htm` uploaden: IIS zet de app stil en geeft de DLL's vrij; vijf seconden wachten.
3. Map voor map uploaden (één lftp-sessie per stap, stoppen bij een fout). **Alleen `wwwroot/admin` wordt opgeruimd** (verwijderen van bestanden die niet meer in de release zitten); nergens anders `--delete`.
4. De bestanden in de root, de `web.config` als laatste.
5. `app_offline.htm` verwijderen: de app start (op de eerste uitrol maakt de eerste start de database-tabellen, zie 5).
6. Health-check (tot ongeveer twee minuten, voor de eerste start).
Nooit aangeraakt of geüpload: `appsettings.Production.json` (alleen op de server, door Bryan), `uploads/` (de mediamap), `logs/` (stdout-log) en `wwwroot/web` (de prerendered website; die uploadt het ASF-project zelf met `--delete` binnen die map). Het script weigert te lopen als de doelmap `wwwroot/web` is of als het artefact een van die dingen bevat.
Faalt de upload halverwege, dan **blijft `app_offline.htm` staan**: bezoekers krijgen de onderhoudspagina in plaats van een half bijgewerkte app. Los het op en draai de upload opnieuw (hij is herhaalbaar), of draai terug (zie 6).
Lokaal proberen zonder iets te wijzigen: `DRY_RUN=1 scripts/deploy-asf-iis-ftps.sh <map>` toont wat er zou worden geüpload (met dezelfde variabelen als in de job; `lftp` moet geïnstalleerd zijn).
## 4. Samenwerking met de website-upload van het ASF-project
Het ASF-project uploadt de prerendered website (inclusief `redirects.json`) met FTPS naar **`<hostmap>/wwwroot/web`**, in drie rondes met een eigen `--delete` alleen in die map. Afspraken:
- De host-upload sluit `wwwroot/web` uit; de website-upload raakt niets buiten `wwwroot/web` aan en zet er zelf geen `web.config` neer.
- **Nooit tegelijk** draaien: op dezelfde FTP-account en in dezelfde mapstructuur. Eerst de host, dan de website.
- Een host-release hoeft de website niet opnieuw te uploaden, en andersom ook niet.
- Beide gebruiken dezelfde FTPS-instellingen (zie het script); de host voegt `net:timeout 30` en `net:reconnect-interval-base 5` toe, de website-upload heeft die niet nodig.
## 5. De eerste uitrol op een lege database
Alleen na Bryans go. Vooraf, door Bryan:
1. **Back-up** van de WordPress-site en de database `andreaslop` (WordPress mag daarna weg; de database blijft ongemoeid).
2. De oude WordPress-bestanden uit de hostmap halen (`index.php`, `wp-*`, de oude `web.config` met rewrite-regels), **behalve** de nieuwe map `uploads`. Een oude WordPress-`web.config` zou botsen met de nieuwe.
3. In de hostmap een map `logs` maken (schrijfrechten voor de application pool-identiteit); schrijfrechten voor `uploads` zetten.
4. `appsettings.Production.json` met de hand naast de plek van de `.exe` zetten, volgens sectie 3 van de configuratiedoc (databasegegevens, JWT-sleutel, setup-token, mail, `Media:Directory`, Sentry). `Website:NoIndex` blijft `true`.
5. In Gitea de variabelen controleren (`ASF_PROD_DEPLOY_PATH` is nu het echte hosterpad; test eerst `DRY_RUN=1`), en `ASF_PROD_DEPLOY_ENABLED=true` zetten.
De uitrol:
1. Release-branch `release/...` van `master`, dispatch met `deploy_asf_production` aangevinkt.
2. De pijplijn bouwt, controleert en uploadt (sectie 3). **De eerste start** maakt alle tabellen (migraties van Core, Identity, Availability, Offerings, Hero, Media, Contact) op de lege MariaDB. Controleer het stdout-log (`logs/stdout_*.log`) op fouten ("Fout bij het activeren van module"), op `Image library Magick.NET self-test passed` en op de Hero-melding; controleer daarna `/api/v1/System/capabilities`.
3. Open `https://andreaslop.nl/admin`: de setuppagina vraagt het **setup-token** en maakt de **eerste beheerder** aan.
4. Haal daarna `Identity:Setup:Token` uit `appsettings.Production.json` (herlaad of recycle de pool).
5. Test de mediamap: een foto uploaden, controleren dat er een bestand in `uploads` staat en dat de map niet via de browser bereikbaar is (zie 1e van de configuratiedoc).
6. De website-upload van het ASF-project naar `<hostmap>/wwwroot/web` laten draaien; controleer de homepage, `/sitemap.xml` en dat `/redirects.json` een 404 geeft.
7. Pas op het release-moment, na Bryans go: `Website:NoIndex` naar `false`, en pas dan de domeinwissel/DNS. Haal `ASF_PROD_DEPLOY_ENABLED` weer weg.
**Het stdout-log uit:** na de eerste *succesvolle* start (stap 2 en 3 zijn gelukt) zet Bryan in de `web.config` op de server `stdoutLogEnabled="false"`. Anders groeien de bestanden in `logs/` onbeperkt. Let op: een volgende deploy zet de `web.config` uit het sjabloon terug en dus `stdoutLogEnabled` weer op `true`. Zet het sjabloon daarom na de eerste uitrol in een aparte, kleine PR op `false`; tot die PR er is, zet Bryan het na elke deploy handmatig uit.
## 6. Terugdraaien
- **De vorige release** is het artefact `app-asf-production-win-x64` van de vorige run (30 dagen bewaard in Gitea). Elke run bewaart zijn eigen artefact; noteer bij elke uitrol welke run live staat.
- **Terugzetten:** `app_offline.htm` uploaden (of de upload-job draaien met het oude artefact), de oude release uploaden met hetzelfde script (`scripts/deploy-asf-iis-ftps.sh <uitgepakte map>` met de FTPS-variabelen uit de job), daarna `app_offline.htm` verwijderen. Het script doet dit hele traject; je hoeft alleen het oude artefact te downloaden en uit te pakken.
- **Database:** de host draait migraties vooruit en niet terug. Voor een release met een migratie die iets verwijdert is vooraf een database-back-up (herstelpunt) verplicht; zie `production-rollout.md` van de mediabibliotheek. Een code-rollback van een release zonder migratie vraagt niets van de database.
- **Wat een rollback niet raakt:** `appsettings.Production.json`, `uploads/`, `logs/` en `wwwroot/web`.
## 7. Open punten voor Bryan en SLS
1. Het echte hosterpad voor `ASF_PROD_DEPLOY_PATH` (en daarmee of de website-map `wwwroot/wwwroot/web` wordt).
2. Heeft het FTP-account schrijfrechten in de hostmap voor `app_offline.htm`? Faalt de eerste proefupload hier, meld het.
3. Is `lftp` op de Gitea-runner aanwezig (of mag de job het installeren)? De job probeert `apt-get`; anders de runner-image aanpassen.
4. Wat doet de hoster al aan HTTP naar HTTPS en www naar apex (zie 2a van de configuratiedoc)?
## 8. Bekend probleem: certificaatketen van de FTPS-server (2026-11-19)
De eerste uitrol (run 911, stap 1/6 van `scripts/deploy-asf-iis-ftps.sh`) faalde op `Certificate verification: The certificate is NOT trusted. The certificate chain uses expired certificate`: de keten van de FTPS-server van de hoster bevat een verlopen certificaat. Het script controleert het servercertificaat standaard (`ssl:verify-certificate yes`) en moet dat blijven doen.
- Is de controle voor een uitrol bewust uitgezet, dan blijven AUTH TLS en versleuteling aan (`ssl-force`, `ssl-protect-data`); alleen de identiteit van de server is dan niet gecontroleerd, en de inloggegevens kunnen door een man-in-the-middle worden onderschept. Dat mag alleen eenmalig, met Bryans expliciete besluit, en nooit op `master`.
- **De controle moet weer aan** (`yes`) zodra de hoster de keten heeft hersteld, of zodra het CA-certificaat is vastgezet (`set ssl:ca-file <pad>`). Controleer na een herstel met het commando hieronder en met een proefupload (`DRY_RUN=1`).
De keten van de FTP-server bekijken (voor de hoster; het wachtwoord is hiervoor niet nodig):
```sh
openssl s_client -connect <host>:<poort> -starttls ftp -showcerts </dev/null
```
Kijk in de uitvoer naar `Certificate chain` (de certificaten `0`, `1`, ...) en naar `Verify return code`. Een verlopen tussen- of rootcertificaat toont zich als `certificate has expired` (code 10) of `unable to get local issuer certificate`. De geldigheid per certificaat:
```sh
openssl s_client -connect <host>:<poort> -starttls ftp -showcerts </dev/null 2>/dev/null | awk '/BEGIN CERT/{c++} c{print > "chain-" c ".pem"}' ; for f in chain-*.pem; do openssl x509 -in "$f" -noout -subject -issuer -dates; done
```