SlpSoftware/aidlc-docs/features/react-frontend/operations/deployment/deployment-instructions.md

Deployment Instructions

Overview

Deployment gebeurt via Gitea Actions, opgesplitst in twee bestanden:

• .gitea/workflows/continuous_integration.yaml — build/test/lint-gate, plus de deploy-test job.
• .gitea/workflows/deploy.yaml — herbruikbare workflow die dist/ via SCP naar een omgeving uploadt.

Sinds deze stap wordt er automatisch gedeployed naar een testomgeving: een Raspberry Pi die de site serveert via nginx, bereikbaar achter een tweede Raspberry Pi met een nginx reverse proxy.

Pipeline Files

• continuous_integration.yaml — getriggerd door pull_request (build/test/lint-gate), push naar master, en handmatig via workflow_dispatch.
  • Heeft bovenaan een env:-blok (NODE_VERSION, PNPM_VERSION) — pas de Node/pnpm-versie hier op één plek aan, gebruikt wordt dit door alle setup-node/pnpm/action-setup-stappen.
  • prepare → build (uploadt dist artifact) → test (lint + unit tests)
  • deploy-test (alleen bij workflow_dispatch of een push naar master) roept deploy.yaml aan met environment: test en deploy_path: /html/test/slpsoftware
• deploy.yaml — download de dist-artifact en upload de inhoud via appleboy/scp-action naar de opgegeven deploy_path op de host uit de meegegeven secrets. deploy_path/environment/artifact_name zijn al herbruikbare inputs bovenaan dit bestand (workflow_call.inputs).

Waarom staan deploy_path/environment niet ook in het env:-blok?

Gitea/GitHub Actions ondersteunt geen env-context in de with:-sectie waarmee een reusable workflow wordt aangeroepen (jobs.<job_id>.with) — dat werkt alléén binnen jobs.<job_id>.steps. Daarom moeten artifact_name, environment en deploy_path in de deploy-test-job in continuous_integration.yaml letterlijk blijven staan; dit is een beperking van Actions zelf, niet iets dat hier is opgelost. Wil je dit pad wijzigen, pas dan die regels rechtstreeks aan (zie ook de eerdere uitleg hierover).

Eenmalige Setup — Gitea Secrets

Voeg deze secrets toe in Gitea: Repository → Settings → Actions → Secrets:

Secret	Waarde
PI_MAIN_HOST	Intern IP-adres van de webserver-Pi (192.168.1.103)
PI_MAIN_PORT	SSH-poort (2224)
PI_MAIN_USERNAME	SSH-gebruikersnaam (webadmin)
PI_MAIN_PASSWORD	Het SSH-wachtwoord van deze gebruiker

Deze secrets heten PI_MAIN_* (niet PI_TEST_*), omdat dezelfde Pi (Pi Main) en dezelfde inloggegevens naar verwachting ook voor toekomstige omgevingen/webhosts gebruikt worden. Mocht dat later veranderen, dan worden hiervoor alsnog omgeving-specifieke secrets geïntroduceerd.

Eenmalige Setup — Domeinnaam & DNS

• Test: test.slpsoftware.nl → moet als DNS A-record wijzen naar het publieke IP van de reverse-proxy-Pi.
• Productie (nog niet automatisch gedeployed, maar domein al bekend): slpsoftware.nl (en www.slpsoftware.nl) → zelfde reverse-proxy-Pi, zodra productie wordt opgezet.

Eenmalige Setup — nginx & SSL op de Raspberry Pi's

1. Kopieer operations/deployment/nginx/webserver-nginx.conf.example naar /etc/nginx/sites-available/ op de webserver-Pi, maak een symlink in sites-enabled/, en herlaad nginx.
2. Kopieer operations/deployment/nginx/reverse-proxy-nginx.conf.example naar /etc/nginx/sites-available/slpsoftware-test.conf op de reverse-proxy-Pi, maak een symlink in sites-enabled/, en herlaad nginx. Dit bestand gebruikt al test.slpsoftware.nl als server_name.
3. Vraag op de reverse-proxy-Pi een SSL-certificaat aan met certbot (Let's Encrypt), nadat het DNS-record klopt: sudo certbot --nginx -d test.slpsoftware.nl. Certbot regelt automatisch de HTTPS-configuratie en de HTTP→HTTPS-redirect (net zoals je gewend bent van certbot).
4. Zorg dat de map /html/test/slpsoftware bestaat op de webserver-Pi en schrijfbaar is voor de gebruiker webadmin (bijv. sudo mkdir -p /html/test/slpsoftware && sudo chown webadmin:webadmin /html/test/slpsoftware).
5. Voor later, wanneer productie wordt opgezet: zie operations/deployment/nginx/reverse-proxy-nginx-production.conf.example (domein slpsoftware.nl, certbot-commando alvast gedocumenteerd).

How to Deploy to Test

Automatisch

Merge een pull request naar master — de deploy-test job draait dan automatisch na een groene build/test-run.

Handmatig

1. In Gitea, open de repository's Actions tab.
2. Selecteer de Continuous Integration workflow.
3. Klik Run workflow, kies de gewenste branch/ref, en start.

Verifying a Deployment

1. Bevestig dat de Gitea Actions run succesvol is (alle jobs groen, inclusief deploy-test).
2. Open de testomgeving in de browser (via het adres/IP dat je bij de reverse-proxy hebt ingesteld) en controleer dat de site correct laadt (check de browserconsole op fouten, zoals in de handmatige smoke test in construction/build-and-test/integration-test-instructions.md).

Future Work

• Van wachtwoord naar SSH-key: vervang password: ${{ secrets.PI_MAIN_PASSWORD }} in deploy.yaml door key: ${{ secrets.PI_MAIN_SSH_KEY }} (een nieuwe secret met de private key-inhoud), en zet de bijbehorende public key in ~/.ssh/authorized_keys van de webadmin-gebruiker op de webserver-Pi. Verwijder daarna het wachtwoord-secret.
• Productie-omgeving: voeg een deploy-production-job toe zodra de definitieve productiehosting bekend is (zie deployment-plan.md's "Open Item"), en pas nginx/reverse-proxy-nginx-production.conf.example (domein slpsoftware.nl) toe zodra de webserver-locatie voor productie vastligt.