SLP_Software/SlpSoftware
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add automated test-environment deploy via SCP with nginx reverse proxy, domain names and SSL (certbot) setup

Browse Source 
Co-authored-by: Junie <junie@jetbrains.com>
This commit is contained in:
Sluijsens
2026-07-24 15:52:16 +02:00
co-authored by Junie
parent a437bad95b
commit 1ffe884eba
9 changed files with 273 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files
aidlc-docs/features/react-frontend/operations/deployment/deployment-instructions.md
+41 -25
View File
@@ -1,36 +1,52 @@
# Deployment Instructions
## Overview
Deployment is currently a **manually-triggered Gitea Actions pipeline**: `.gitea/workflows/deploy.yml`. You start it yourself from the Gitea Actions UI; it runs the build/test/lint gate and then packages the `dist/` build as a downloadable artifact. There is no automatic upload to a host yet — you upload the artifact yourself for now.
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.
## Pipeline File
`.gitea/workflows/deploy.yml` — triggered by `workflow_dispatch` only (no automatic trigger on push/tag). Two jobs:
- `build-and-test` — install, lint, unit tests, build; uploads `dist/` as the `dist` artifact
- `deploy` — downloads that artifact and republishes it as `release-dist` (placeholder for a future automatic upload step)
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.
## How to Prepare and Run a Release
## Pipeline Files
- `continuous_integration.yaml` — getriggerd door `pull_request` (build/test/lint-gate), `push` naar `master`, en handmatig via `workflow_dispatch`.
- `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.
### 1. Create a release branch (manual, your own git flow)
```bash
git checkout master
git pull
git checkout -b release/1.0.0
git push origin release/1.0.0
```
## Eenmalige Setup — Gitea Secrets
Voeg deze secrets toe in Gitea: **Repository → Settings → Actions → Secrets**:
### 2. Trigger the pipeline manually
1. In Gitea, open the repository's **Actions** tab.
2. Select the **Build, Test and Package Release** workflow.
3. Click **Run workflow**, choose the `release/1.0.0` branch (or whichever ref you want to build), and start it.
| Secret | Waarde |
|---|---|
| `PI_TEST_HOST` | Intern IP-adres van de webserver-Pi (`192.168.1.103`) |
| `PI_TEST_PORT` | SSH-poort (`2224`) |
| `PI_TEST_USERNAME` | SSH-gebruikersnaam (`webadmin`) |
| `PI_TEST_PASSWORD` | Het SSH-wachtwoord van deze gebruiker |
### 3. Download and upload the artifact
1. Once the run finishes successfully, open the run's summary page in Gitea Actions.
2. Download the **release-dist** artifact (a zip of the `dist/` folder).
3. Upload its contents to your host manually (e.g. via your FTP/SFTP client), using whatever hosting setup you finalize with mijnhostingpartner.nl.
## 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. Confirm the Gitea Actions run completed successfully (`build-and-test` and `deploy` both green).
2. After manually uploading the artifact contents, open the live site in a browser and confirm it loads correctly (check the browser console for errors, per the manual smoke test in `construction/build-and-test/integration-test-instructions.md`).
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 — Automatic Upload
Once the hosting setup is finalized (FTP/SFTP details, and whether this frontend shares a domain/app with a future back-end and CMS front-end — see `deployment-plan.md`'s "Open Item"), replace the placeholder step in the `deploy` job with an actual upload step (e.g. an FTP/SFTP action, or a shell-based upload using `lftp`/`curl`), using Gitea Actions Secrets for credentials and Variables for host/paths. At that point, decide whether the trigger should stay manual or become automatic (e.g. on push to `release/*` or on tag).
## Future Work
- **Van wachtwoord naar SSH-key**: vervang `password: ${{ secrets.PI_TEST_PASSWORD }}` in `deploy.yaml` door `key: ${{ secrets.PI_TEST_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.