Files
slp-modular-cms/docs/deploy-en-testomgevingen.md
T

109 lines
12 KiB
Markdown

# Deploy en testomgevingen
Compact overzicht van hoe code op de testomgevingen en productie komt. Bron: `.gitea/workflows/continuous_integration.yaml` (hierna `ci`) en `.gitea/workflows/deploy-scp.yaml` (hierna `deploy`), gecontroleerd op 2026-11-15. De installatie van de host zelf staat niet hier maar in `aidlc-docs/features/gitea-deployment-workflow/operations/deployment/deployment-instructions.md` en `aidlc-docs/features/andreaslop-site-hosting/operations/deployment/deployment-instructions.md`.
## Omgevingen
| Omgeving | Wat | Publieke URL en health | Deploy-job |
|---|---|---|---|
| SlpSoftware test | `SlpModularCms.Api.SlpSoftware` | `https://test.slpsoftware.nl`, health `https://test.slpsoftware.nl/health` | `deploy-sls-test` |
| SlpSoftware productie | `SlpModularCms.Api.SlpSoftware` | `https://slpsoftware.nl`, health `https://slpsoftware.nl/health` | `deploy-sls-production` |
| ASF test (Andrea Slop Fotografie) | `SlpModularCms.Api.AndreaSlopFotografie` (website + admin met thema `asf`) | `https://test.andreaslop.nl`, health `https://test.andreaslop.nl/health` | `deploy-asf-test` |
De werkelijke health-URL's komen uit de Gitea-variabelen `HEALTH_CHECK_URL_TEST`, `HEALTH_CHECK_URL_PRODUCTION` en `HEALTH_CHECK_URL_ASF_TEST`; de waarden staan niet in de repository. De hostnamen hierboven komen uit de feature-documentatie (`deployment-instructions.md` van `gitea-deployment-workflow` en `andreaslop-site-hosting`) en zijn niet uit de workflows zelf af te leiden. Er is geen productie-deploy voor ASF in deze pipeline (de ASF-productie draait apart op IIS, zie `aidlc-docs/active-features.md`).
## Wanneer draait wat
| Trigger | Wat er gebeurt |
|---|---|
| `pull_request` (opened, synchronize, reopened) | De poorten voor het master-CMS (`SlpModularCms.Api` met alle modules, Core, alle testprojecten via `SlpModularCms.Ci.slnf`; kwetsbaarheidscontrole; frontend build/test/lint) en de niet-verplichte `compile-sites` (alleen compileren van de dunne site-projecten). Er wordt **niet** gepubliceerd of gedeployed: een site wordt pas gebouwd bij een deploy. Een nieuwe push naar dezelfde PR annuleert de lopende run. |
| `push` op `master` | Dezelfde poorten, daarna automatisch `deploy-sls-test` (SlpSoftware test) en, als `ASF_TEST_DEPLOY_ENABLED` op `true` staat, ook `deploy-asf-test`. Nooit productie. |
| `workflow_dispatch` (handmatig, op elke gekozen branch) | Alle poorten draaien altijd volledig (het pad-filter meldt dan backend en frontend als gewijzigd). Deployen gebeurt alleen voor de aangevinkte invoer, zie hieronder. |
Poorten (jobs): `changes` (pad-filter), `backend-build`, `backend-test` (met een MariaDB-servicecontainer op poort 3308), `vulnerability-scan`, `frontend-prepare`, `frontend-build`, `frontend-test`, `frontend-lint`. Een poort die overgeslagen is (omdat die kant van de repo niet wijzigde) blokkeert niet; een poort die faalt of wordt geannuleerd blokkeert elke publish. Pad-filter bij push/PR: backend = `src/**`, `tests/**`, `*.sln`, `**/*.csproj` en de workflowbestanden; frontend = `frontend/**` en de workflowbestanden. Een run die geen van beide raakt publiceert niets.
### Invoer van `workflow_dispatch`
| Invoer | Standaard | Effect |
|---|---|---|
| `deploy_sls_test` | uit | Bouwt (`publish-sls-test`) en deployt naar SlpSoftware test |
| `deploy_sls_production` | uit | Bouwt (`publish-sls-production`) en deployt naar SlpSoftware productie, met databaseback-up vooraf |
| `deploy_asf_test` | uit | Bouwt (`publish-asf-test`) en deployt naar ASF test; alleen als ook `ASF_TEST_DEPLOY_ENABLED` op `true` staat |
Zonder een van de drie aangevinkt draaien alleen de poorten (handig als losse CI-run). Meerdere tegelijk aanvinken kan. Let op: `deploy_sls_production` is aan de `master`-branch niet gebonden in de workflow: de conditie van `deploy-sls-production` controleert alleen de gebeurtenis en de invoer, niet de branch (zie `ci`, job `deploy-sls-production`).
## Jobnamen en branch protection (merge-checklist)
Jobnamen volgen `{actie}-{site}-{omgeving}`: `config-sls`, `publish-sls-test`, `deploy-sls-test`, `publish-sls-production`, `deploy-sls-production` en voor Andrea `config-asf`, `publish-asf-test`, `deploy-asf-test`. Ook de invoeren van de handmatige run hebben de sitenaam: `deploy_sls_test`, `deploy_sls_production` en `deploy_asf_test` (vroeger `deploy_test` en `deploy_production`). De uitvoer van `config-sls` heet `artifact_name_sls_*`, `deploy_environment_sls_*`, `deploy_path_sls_*`, `service_name_sls_*` en `health_check_url_sls_*`, de artefacten `app-sls-test` en `app-sls-production` (ASF: `app-asf-test`). De Gitea-variabelen en -secrets (bijv. `DEPLOY_PATH_TEST`) zijn niet hernoemd.
Wat de CI per site doet: bij een pull request bouwt en test de CI alleen het master-CMS (alle modules, `SlpModularCms.Ci.slnf`). De sites (`Api.SlpSoftware`, `Api.AndreaSlopFotografie`, `Api.Slave`) zijn dunne composities zonder eigen logica; hun samenstelling en standaardwaarden worden getest op de master-host (`SiteContractTests`, `AsfVariantPipelineTests`, `SiteVariantContactTests`), `compile-sites` controleert dat ze nog compileren (niet verplicht) en `publish-*` bouwt een site pas bij een deploy (push naar `master` of een aangevinkte invoer). Na elke test-deploy draait een rooktest (`scripts/smoke-site.sh`, jobs `smoke-sls-test` en `smoke-asf-test`: health, modulelijst in `/System/capabilities`, noindex, beschermde beheerroutes, 404 op een onbekend pad bij ASF); faalt die, dan faalt de run.
Branch protection op `master`: verplicht zijn alleen `Continuous Integration / backend-test (pull_request)` en `frontend-test (pull_request)`. De eerdere verplichte check `publish-test (pull_request)` bestaat niet meer (er wordt bij een pull request niet meer gepubliceerd) en **moet vóór de merge uit de vereiste checks worden gehaald** (Gitea: repository, Instellingen, Branches, beschermde branch `master`, vereiste statuschecks), anders wacht de merge op een check die nooit meer draait. Pas dat vlak voor de merge aan, met Bryans go.
## Een branch naar test deployen
1. Gitea, repository, Actions, workflow "Continuous Integration", "Run workflow".
2. Kies de branch (de workflow bouwt en deployt de code van de gekozen ref; `actions/checkout` zonder `ref`).
3. Vink `deploy_sls_test` aan (SlpSoftware test) en/of `deploy_asf_test` (ASF test). Laat `deploy_sls_production` uit.
4. Na een groene run controleert de deploy zelf `/health`; kijk daarna zelf op de testhost.
Aandachtspunten:
- De selectie van een branch in de Gitea-interface en het uitvoeren op een andere branch dan `master` is door mij niet in de interface uitgeprobeerd (niet geverifieerd); de workflow zelf kent geen beperking tot `master` voor de testdeploys.
- Naar verwachting gebruikt Gitea het workflowbestand van de gekozen branch; dan moet de invoer `deploy_asf_test` daar in de workflow staan (niet geverifieerd).
- De testdatabase blijft bestaan. Bij het opstarten past de applicatie migraties toe (`MigrateCoreDatabase()` voor Identity/Core, en per module `Database.Migrate()`, zie README). Deploy je later weer `master`, dan staan de migraties van de branch nog in die database; dat gaat alleen goed als migraties voorwaarts-compatibel zijn (zo beschreven in `rollback-plan.md`).
- Een volgende push naar `master` overschrijft wat er op test staat.
- De testdeploys maken geen databaseback-up (`run_db_backup: false`).
## Wat `deploy` doet (per release)
1. Controleert dat `deploy_path`, `service_name` en `health_check_url` niet leeg zijn; anders stopt de deploy voordat de host wordt aangeraakt.
2. Zet SSH klaar: met de sleutel in `PI_MAIN_SSH_KEY` als die is ingesteld en werkt, anders met wachtwoord (`sshpass`).
3. Alleen productie: `bash ~/scripts/backup-slpsoftware-db.sh <omgeving>` op de host (het script staat niet in deze repository).
4. Uploadt het artefact naar `<deploy_path>/releases/<UTC-tijdstempel>`.
5. Koppelt de blijvende websitemap `shared/wwwroot-web` als `wwwroot/web` in de release, en eventuele `shared/modules/*.dll`.
6. Zet de symlink `<deploy_path>/current` in één stap om naar de nieuwe release en herstart de `systemd --user`-service (`service_name`).
7. Controleert `health_check_url` met `curl -f`, 10 pogingen met 3 seconden pauze. Slaagt dat niet, dan faalt de job.
8. Alleen na een geslaagde health-check: verwijdert oude releases, zodat `current` en één vorige release overblijven (`ls -1t | tail -n +3`).
9. Verwijdert de tijdelijke sleutel (ook bij falen).
## Rollback voor zover in de workflows beschreven
- Er is **geen automatische rollback**. Faalt de health-check, dan blijft `current` naar de nieuwe release wijzen en wordt er niet opgeruimd; de vorige release staat dan nog op schijf (opmerkingen in `deploy`).
- Handmatig terug: op de host `current` naar de vorige release in `releases/` zetten en de service herstarten. De exacte stappen staan in `aidlc-docs/features/gitea-deployment-workflow/operations/deployment/rollback-plan.md`.
- Verder terug dan de vorige release: een eerdere commit opnieuw deployen via de pijplijn (push naar `master`, of dispatch). Of de databasemigraties dat toelaten hangt af van die migraties (zie hierboven).
- Productie heeft een databaseback-up vooraf; terugzetten staat in dezelfde `rollback-plan.md`.
## Vereiste Gitea-secrets en -variabelen (alleen namen)
Secrets (SSH naar de host):
| Naam | Gebruik |
|---|---|
| `PI_MAIN_ADDRESS`, `PI_MAIN_PORT`, `PI_MAIN_USERNAME` | Adres, poort en deploy-account |
| `PI_MAIN_PASSWORD` | Wachtwoord (terugval; werkt vanaf de runner die op de host mag inloggen met wachtwoord) |
| `PI_MAIN_SSH_KEY` | Optioneel: privésleutel van het deploy-account, nodig voor runners die niet met wachtwoord mogen |
Variabelen:
| Naam | Voor |
|---|---|
| `DEPLOY_PATH_TEST`, `SERVICE_NAME_TEST`, `HEALTH_CHECK_URL_TEST` | SlpSoftware test. De `config-sls`-job faalt als een van deze drie leeg is (dat geldt voor elke run, ook een PR) |
| `DEPLOY_PATH_PRODUCTION`, `SERVICE_NAME_PRODUCTION`, `HEALTH_CHECK_URL_PRODUCTION` | SlpSoftware productie |
| `ASF_TEST_DEPLOY_ENABLED` | Schakelaar voor alle ASF-jobs; alleen de waarde `true` zet ze aan |
| `DEPLOY_PATH_ASF_TEST`, `SERVICE_NAME_ASF_TEST`, `HEALTH_CHECK_URL_ASF_TEST` | ASF test; `config-asf` faalt als er een leeg is (terwijl de schakelaar aan staat) |
| `VITE_SENTRY_DSN` | Sentry-DSN voor de SlpSoftware-adminbuild (test en productie) |
| `VITE_SENTRY_DSN_ASF` | Sentry-DSN voor de ASF-adminbuild |
| `VITE_UMAMI_SCRIPT_URL`, `VITE_UMAMI_WEBSITE_ID_TEST`, `VITE_UMAMI_WEBSITE_ID_PRODUCTION` | Umami voor de SlpSoftware-adminbuild (ASF gebruikt geen Umami) |
| `SECURITY_ALLOWED_SCRIPT_ORIGINS_TEST`, `SECURITY_ALLOWED_SCRIPT_ORIGINS_PRODUCTION` | Alleen gebruikt als controle in `publish-sls-test`/`publish-sls-production` wanneer `VITE_UMAMI_SCRIPT_URL` gevuld is: de Umami-origin moet in deze lijst staan, en de lijst moet overeenkomen met `SecurityHeaders__AllowedScriptOrigins__0` op de host |
Runtime-instellingen van de applicatie (verbindingsstring, JWT, mail, `Contact__*`, Sentry) zitten niet in de workflow maar in het omgevingsbestand op de host (`shared/env`, zie README en de hostdocumentatie).
## Runners
Alle jobs draaien op het label `linux`, zodat elke runner (de Pi en de desktop-runner) ze kan oppakken. Gebouwd wordt voor `linux-arm64` (`PUBLISH_RID`), framework-dependent. Artefacten worden 1 dag bewaard.
## Captcha
Het captcha van het contactformulier staat uit (`Contact:Captcha:Enabled=false`) tot Bryan een aanbieder kiest. De vergelijking van de opties, de gevolgen voor CSP, privacy en werk en de beslisrij staan in [captcha-providers.md](captcha-providers.md). Zet het captcha pas aan na dat besluit, met de sleutels alleen via omgevingsvariabelen.