Installeren
schakl. draait als één Docker Compose-stack: web, api, worker, db (PostgreSQL),
redis en een ingress. Er zijn twee kant-en-klare varianten:
| Bestand | Ingress | Gebruik wanneer |
|---|---|---|
infra/compose.yaml | Traefik, publiceert poorten | de host waarop schakl. zelf :80/:443 beheert |
infra/compose.tunnel.yaml | geen (je bestaande cloudflared) | de host draait al een Cloudflare Tunnel |
De worker hergebruikt de API-image; er bestaan dus maar twee images:
ghcr.io/schakl-app/schakl-api en ghcr.io/schakl-app/schakl-web.
Vereisten
Section titled “Vereisten”- Een host met Docker en Docker Compose (of Portainer).
- Een hostnaam die naar de server wijst; de hostnaam bepaalt welke organisatie geladen wordt, dus installeer meteen op het adres dat je wilt houden.
- Toegang tot de images op GHCR (privé): een GitHub-token met alleen
read:packages.
Omgevingsvariabelen
Section titled “Omgevingsvariabelen”Vier variabelen zijn verplicht en hebben géén default:
| Variabele | Betekenis |
|---|---|
POSTGRES_ADMIN_PASSWORD | wachtwoord van de Postgres-superuser |
APP_DB_PASSWORD | wachtwoord van de applicatierol schakl_app |
SCHAKL_SECRET_KEY | geheime sleutel voor sessies en tokens |
SCHAKL_BASE_DOMAIN | basisdomein; de app is bereikbaar op app.<basisdomein> |
Pin daarnaast SCHAKL_TAG op een exacte versie (bijv. 1.2.3) in plaats van latest;
zie Updaten & back-ups.
Eerste start
Section titled “Eerste start”-
Deploy de stack vanuit Git (Portainer: Stacks → Add stack → Repository), niet door YAML in de web-editor te plakken; relatieve paden verliezen anders hun betekenis.
-
Wacht tot
apihealthy is. De API draait bij het opstarten eerst alle databasemigraties; een databaseprobleem uit zich dus als een herstartendeapi, nooit als een half-werkende app. -
Open de app in de browser. Elke route komt uit bij
/setup: de eerste-start-wizard maakt in één stap de organisatie, de huisstijl, de taal en het eigenaarsaccount aan. De wizard sluit definitief zodra de eerste organisatie bestaat; er is geen seed-stap. -
De hostnaam waarop je de wizard doorloopt wordt geclaimd als geverifieerd eigen domein van de organisatie. Draai de wizard dus op het adres dat je wilt houden.
Hostnamen zijn strikt
Section titled “Hostnamen zijn strikt”Een verzoek komt op precies twee manieren bij een organisatie uit: via een geverifieerd
eigen domein, of via <slug>.<SCHAKL_BASE_DOMAIN>. Een onbekende hostnaam is een 404;
er is bewust géén terugval naar “de enige organisatie”. Een extra domein koppel je later
onder Instellingen → Huisstijl → Eigen domein; het wordt actief na een DNS
TXT-verificatie.
Health-endpoints
Section titled “Health-endpoints”| Endpoint | Auth | Doel |
|---|---|---|
GET /health | geen | liveness: goedkoop, raakt de database niet |
GET /health/ready | geen | readiness: controleert Postgres, Redis en migraties, zonder details prijs te geven |
GET /api/v1/system/info | eigenaar/beheerder | het scherm Instellingen → Systeem: versies, migratiestand, worker-heartbeat |