516a048ce7
Some checks are pending
dev - build & deploy naar test / build-and-deploy (push) Waiting to run
131 lines
5.1 KiB
Markdown
131 lines
5.1 KiB
Markdown
# Teach
|
|
|
|
Digibord-webapp (Fastify + static frontend) met PostgreSQL, gecontaineriseerd en
|
|
via Forgejo Actions automatisch uitgerold: `dev` → test-VM, release → productie-VM.
|
|
|
|
## Structuur
|
|
|
|
```
|
|
teach/
|
|
├─ public/index.html # de digibord-app (voorheen teach.html)
|
|
├─ src/server.js # Fastify: serveert de app + /api + DB-pool
|
|
├─ db/001_init.sql # initieel Postgres-schema
|
|
├─ Dockerfile # productie-image (non-root, healthcheck)
|
|
├─ compose.yaml # lokaal draaien (app + postgres)
|
|
├─ deploy/compose.deploy.yaml # test/prod: pullt image uit de registry
|
|
├─ .forgejo/workflows/
|
|
│ ├─ dev.yaml # push naar dev → build + deploy test
|
|
│ └─ release.yaml # release → build + deploy prod
|
|
└─ .env.example
|
|
```
|
|
|
|
## Lokaal draaien
|
|
|
|
```bash
|
|
cp .env.example .env # pas POSTGRES_PASSWORD en DATABASE_URL aan
|
|
docker compose up --build
|
|
```
|
|
|
|
App op http://localhost:3000, healthcheck op `/healthz`, DB-check op `/readyz`.
|
|
|
|
## Architectuurkeuzes
|
|
|
|
- **Container i.p.v. losse static site**: omdat er een database bijkomt, is een
|
|
backend nodig (browser praat niet rechtstreeks met Postgres). De Fastify-app
|
|
serveert de HTML én biedt de `/api`, en praat met de DB.
|
|
- **Forgejo container registry**: CI bouwt de image één keer en pusht die; beide
|
|
VM's pullen exact dezelfde geteste image. Geen build op de productie-VM.
|
|
- **Nginx blijft ervoor** als reverse proxy / TLS op elke VM; de app luistert
|
|
alleen op `127.0.0.1:<APP_PORT>`.
|
|
|
|
## Eenmalige setup
|
|
|
|
### 1. Repo aanmaken in Forgejo
|
|
Maak een leeg repo (bv. `ramon/teach`) en push (zie onderaan).
|
|
|
|
### 2. Registry / Actions variabelen en secrets
|
|
Onder **Settings → Actions → Variables** van het repo (of org):
|
|
|
|
| Variable | Voorbeeld | Uitleg |
|
|
|------------|--------------------------|---------------------------------|
|
|
| `REGISTRY` | `git.familiebesselink.nl`| Host van je Forgejo = registry |
|
|
|
|
Onder **Settings → Actions → Secrets**:
|
|
|
|
| Secret | Uitleg |
|
|
|--------------------|--------------------------------------------------------------|
|
|
| `REGISTRY_USER` | Forgejo-gebruiker met package-write rechten |
|
|
| `REGISTRY_TOKEN` | Token/wachtwoord voor die gebruiker (scope: packages) |
|
|
| `TEST_HOST` | IP/hostname van de test-VM |
|
|
| `TEST_USER` | SSH-gebruiker op de test-VM |
|
|
| `TEST_SSH_KEY` | Private SSH-key (deploy key) voor de test-VM |
|
|
| `TEST_DEPLOY_PATH` | Pad op de test-VM met `compose.deploy.yaml` + `.env` + `db/` |
|
|
| `PROD_HOST` | IP/hostname van de productie-VM |
|
|
| `PROD_USER` | SSH-gebruiker op de productie-VM |
|
|
| `PROD_SSH_KEY` | Private SSH-key voor de productie-VM |
|
|
| `PROD_DEPLOY_PATH` | Pad op de productie-VM met de deploy-bestanden |
|
|
|
|
> De runner moet Docker + buildx beschikbaar hebben en `actions/checkout`,
|
|
> `docker/*` en `appleboy/ssh-action` kunnen ophalen (standaard van github.com;
|
|
> instelbaar via de runner-config). Pas `runs-on` in de workflows aan naar het
|
|
> label van jouw runner als dat niet `ubuntu-latest` is.
|
|
|
|
### 3. Deploy-map op elke VM
|
|
Op zowel de test- als de productie-VM, in het pad dat je bij `*_DEPLOY_PATH`
|
|
opgeeft:
|
|
|
|
```bash
|
|
mkdir -p teach && cd teach
|
|
# kopieer deze twee uit de repo:
|
|
# deploy/compose.deploy.yaml -> compose.deploy.yaml
|
|
# db/ -> db/
|
|
# maak een .env aan:
|
|
cat > .env <<'EOF'
|
|
IMAGE=git.familiebesselink.nl/ramon/teach:dev # prod: laat CI dit op :vX.Y.Z zetten
|
|
POSTGRES_DB=teach
|
|
POSTGRES_USER=teach
|
|
POSTGRES_PASSWORD=<sterk-wachtwoord>
|
|
DATABASE_URL=postgres://teach:<sterk-wachtwoord>@db:5432/teach
|
|
APP_PORT=3000
|
|
EOF
|
|
```
|
|
|
|
CI werkt bij elke deploy de `IMAGE=`-regel bij, pullt en herstart.
|
|
|
|
### 4. Nginx reverse proxy (per VM)
|
|
```nginx
|
|
server {
|
|
listen 443 ssl;
|
|
server_name digibord.familiebesselink.nl; # test-VM eigen subdomein
|
|
|
|
# ssl_certificate ... (bestaande config)
|
|
|
|
location / {
|
|
proxy_pass http://127.0.0.1:3000;
|
|
proxy_set_header Host $host;
|
|
proxy_set_header X-Real-IP $remote_addr;
|
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
proxy_set_header X-Forwarded-Proto $scheme;
|
|
}
|
|
}
|
|
```
|
|
|
|
## Workflow / branching
|
|
|
|
- Werk op feature-branches, merge naar **`dev`** → automatisch naar test.
|
|
- Tevreden? Maak een **release** (tag `vX.Y.Z`) → automatisch naar productie.
|
|
|
|
## Push naar Forgejo (eerste keer)
|
|
|
|
```bash
|
|
git remote add origin https://git.familiebesselink.nl/ramon/teach.git
|
|
git push -u origin main
|
|
git push -u origin dev
|
|
```
|
|
|
|
## Volgende stap: data uit localStorage naar de database
|
|
|
|
De frontend bewaart borden/gebruikers nu nog in `localStorage`. Om echt een
|
|
gedeelde database te gebruiken, bouwen we `/api`-endpoints (boards, folders,
|
|
users) in `src/server.js` en laten we de frontend die aanroepen i.p.v.
|
|
`localStorage`. Het schema in `db/001_init.sql` is daarvoor het startpunt.
|