Add automated test-environment deploy via SCP with nginx reverse proxy, domain names and SSL (certbot) setup
Co-authored-by: Junie <junie@jetbrains.com>
This commit is contained in:
Junie
@@ -1,30 +1,41 @@
|
||||
# Deployment Plan
|
||||
|
||||
## Chosen Method
|
||||
**A manually-triggered Gitea Actions pipeline** (`workflow_dispatch`) that runs the build/test/lint gate and then packages the `dist/` build as a downloadable artifact. This is an interim setup, deliberately simplified per user feedback after the initial plan: no automatic upload to a host yet — that will be added later once the hosting details are finalized (see "Open Item" below).
|
||||
**Gitea Actions**, opgesplitst in twee workflow-bestanden:
|
||||
- `.gitea/workflows/continuous_integration.yaml` — draait de build/test/lint-gate, automatisch bij elke pull request en bij elke push/merge naar `master`, of handmatig via `workflow_dispatch`.
|
||||
- `.gitea/workflows/deploy.yaml` — een herbruikbare (`workflow_call`) job die de `dist/` build via SCP (over SSH) uploadt naar de webroot van een omgeving.
|
||||
|
||||
Sinds deze stap is er een echte, geautomatiseerde upload naar een **testomgeving**: een Raspberry Pi die de statische site serveert via nginx, achter een tweede Raspberry Pi die als nginx reverse proxy fungeert.
|
||||
|
||||
## How It Works
|
||||
1. You manually create a `release/*` branch when you want to cut a release (e.g. `release/1.0.0`), following your own git flow.
|
||||
2. You manually trigger the pipeline (`Build, Test and Package Release`) from Gitea's Actions UI, picking the branch/ref to run it against (typically the release branch).
|
||||
3. The pipeline always runs `build-and-test` first (install, lint, unit tests, build) as a gate.
|
||||
4. If that succeeds, the `deploy` job downloads the build and republishes it as a `release-dist` artifact, ready to download and upload to the host by hand for now.
|
||||
1. Bij elke pull request draait automatisch de build/test/lint-gate (`prepare` → `build` → `test`), zodat merge requests direct gevalideerd worden.
|
||||
2. Zodra een pull request naar `master` gemerged wordt (of de workflow handmatig via `workflow_dispatch` gestart wordt), draait aanvullend de `deploy-test` job.
|
||||
3. `deploy-test` roept de herbruikbare `deploy.yaml` workflow aan met `environment: test` en `deploy_path: /html/test/slpsoftware`, en geeft via `secrets: inherit` de Pi-inloggegevens door.
|
||||
4. `deploy.yaml` downloadt de `dist`-artifact en uploadt de inhoud via SCP (wachtwoord-login) naar de webserver-Pi op het interne netwerk (`192.168.1.103`, poort `2224`).
|
||||
5. nginx op de webserver-Pi serveert de bestanden vanaf `/html/test/slpsoftware`; de reverse-proxy-Pi stuurt binnenkomend verkeer door naar deze webserver-Pi. Voorbeeldconfiguraties staan in `operations/deployment/nginx/`.
|
||||
6. De reverse-proxy-Pi is ook verantwoordelijk voor SSL: certificaten worden net als voorheen aangevraagd via certbot (Let's Encrypt) en HTTP-verkeer wordt doorverwezen naar HTTPS.
|
||||
|
||||
## Environments
|
||||
Simplified to a single flow for now (superseding the earlier dev/staging/production proposal, which is dropped per user feedback — **the staging/production auto-deploy jobs have been removed**):
|
||||
- No automated environment deployments exist yet.
|
||||
- Releases are prepared manually via `release/*` branches; the artifact produced by the pipeline is uploaded to the host manually until an automatic deploy step is added.
|
||||
- **Test** (nieuw, geautomatiseerd): zoals hierboven beschreven — de enige omgeving die op dit moment daadwerkelijk automatisch gedeployed wordt. Domeinnaam: `test.slpsoftware.nl` (SSL via certbot op de reverse-proxy-Pi).
|
||||
- **Productie**: nog niet geautomatiseerd. Zodra de definitieve productiehosting bekend is, kan een vergelijkbare `deploy-production`-job worden toegevoegd die `deploy.yaml` aanroept met `environment: production` en de productie-secrets/pad. Domeinnaam ligt al vast: `slpsoftware.nl` (SSL eveneens via certbot; zie `nginx/reverse-proxy-nginx-production.conf.example`).
|
||||
|
||||
## Automation Level
|
||||
Partially automated (intentionally, for now): build/test/lint and artifact packaging are automated once triggered, but **triggering itself is manual** (`workflow_dispatch`), and the actual upload to the host is also manual (download the `release-dist` artifact from the Gitea Actions run, then upload it yourself, e.g. via an FTP client). This is a deliberate interim step until the hosting setup is finalized.
|
||||
Volledig geautomatiseerd voor de testomgeving: build, test, lint én upload naar de test-Pi gebeuren zonder handmatige tussenstap, zodra er gemerged wordt naar `master` (of handmatig getriggerd wordt). Alleen productie is nog niet geautomatiseerd.
|
||||
|
||||
## Rollback Strategy
|
||||
Version control via git branches/releases: keep `release/*` branches (or tag them) so a previous release's artifact can be regenerated by re-running the pipeline against that branch/tag. See `rollback-plan.md`.
|
||||
Zie `rollback-plan.md` — voor de testomgeving kan een eerdere commit/branch opnieuw gebouwd en geüpload worden door de workflow opnieuw te triggeren.
|
||||
|
||||
## Secrets & Configuration
|
||||
Not yet needed — there is no automated upload step, so no host credentials are configured in Gitea Actions at this stage. When automatic deployment is added later, credentials should be stored as Gitea Actions Secrets (never committed to the repo), consistent with the original decision.
|
||||
Voor de testomgeving zijn de volgende Gitea Actions Secrets (repository-niveau) vereist:
|
||||
- `PI_TEST_HOST` — `192.168.1.103` (intern IP van de webserver-Pi)
|
||||
- `PI_TEST_PORT` — `2224`
|
||||
- `PI_TEST_USERNAME` — `webadmin`
|
||||
- `PI_TEST_PASSWORD` — het SSH-wachtwoord van deze gebruiker
|
||||
|
||||
## Open Item — Automatic Deploy Not Yet Implemented
|
||||
The `deploy` job currently only re-publishes the build as an artifact. Once you decide on the final hosting setup (FTP/SFTP details, and whether this frontend shares a domain/app with a future back-end and CMS front-end), the `deploy` job in `.gitea/workflows/deploy.yml` should be extended to actually upload `dist/` to the host (e.g. via an FTP/SFTP action or a shell-based upload step), reusing Gitea Actions Secrets/Variables for credentials and paths.
|
||||
Dit is bewust wachtwoord-authenticatie (voor nu, zoals gekozen), zodat de testomgeving snel werkend is. Zie "Future Work" in `deployment-instructions.md` voor de overstap naar SSH-key-authenticatie.
|
||||
|
||||
## Open Item — Productie-deploy Nog Niet Geautomatiseerd
|
||||
Zodra de definitieve productiehosting bekend is (en of dit dezelfde soort Raspberry Pi-opstelling is, of een externe hostingpartij), voeg een `deploy-production`-job toe aan `continuous_integration.yaml` die `deploy.yaml` aanroept met `environment: production`, en configureer de bijbehorende secrets (`PI_PROD_*` of vergelijkbaar). Domeinnaam (`slpsoftware.nl`) en SSL-aanpak (certbot/Let's Encrypt op de reverse-proxy-Pi) liggen al vast, zie `nginx/reverse-proxy-nginx-production.conf.example`.
|
||||
|
||||
## Verified Build Prerequisite
|
||||
This plan relies on the Build and Test stage already being verified (`construction/build-and-test/build-and-test-summary.md`): `pnpm run build` produces a static `dist/` bundle with no server-side requirements.
|
||||
Dit plan bouwt voort op de Build and Test-stage (`construction/build-and-test/build-and-test-summary.md`): `pnpm run build` produceert een statische `dist/`-bundel zonder server-side vereisten, geschikt om direct door nginx geserveerd te worden.
|
||||
|
||||
Reference in New Issue
Block a user