Added readme
This commit is contained in:
Sven laptop
@@ -0,0 +1,239 @@
|
||||
# Transit Project
|
||||
|
||||
Dit repository bevat een suite van drie Node.js microservices (APIs) en bijbehorende tooling:
|
||||
|
||||
- `auth_api` — Authenticatie en token-uitgifte (standaard port 5000)
|
||||
- `employee_api` — Employee onboarding / management (standaard port 4000)
|
||||
- `transit_api` — Transit/schedule endpoints (standaard port 5001)
|
||||
|
||||
Er is ook een GitHub Actions workflow aanwezig die Docker images bouwt en pusht naar GitHub Container Registry (GHCR).
|
||||
|
||||
Belangrijk: deze README bevat geen wachtwoorden of andere gevoelige gegevens. Sla secrets altijd buiten versiebeheer op (environment variables, secret managers, Portainer secrets, etc.).
|
||||
|
||||
---
|
||||
|
||||
## Overzicht van inhoud
|
||||
|
||||
- `auth_api/` — source voor auth service
|
||||
- `employee_api/` — source voor employee service
|
||||
- `transit_api/` — source voor transit service
|
||||
- `.github/workflows/docker-build.yml` — CI: bouw en push images naar GHCR
|
||||
- `docker-compose.yml` — compose file die (in deze workspace-versie) images trekt van `ghcr.io/...` en verwacht dat je een externe PostgreSQL hebt draaien
|
||||
- `.env.example` — voorbeeld environment variabelen
|
||||
- `DOCKER_README.md` & `CI_CD_PORTAINER_GUIDE.md` — extra docs voor Docker/CI
|
||||
|
||||
---
|
||||
|
||||
## Vereisten
|
||||
|
||||
- Git
|
||||
- Docker (20.10+)
|
||||
- Docker Compose (v2+ of `docker compose`)
|
||||
- (Optioneel) een remote omgeving met Portainer
|
||||
- (Optioneel) Een GitHub account met rechten om images naar GHCR te publiceren
|
||||
|
||||
---
|
||||
|
||||
## Veiligheid — belangrijke reminders
|
||||
|
||||
- Plaats geen secrets in git. Gebruik een `.env`-bestand lokaal (dat je in `.gitignore` houdt) of een secret manager.
|
||||
- JWT secrets, database wachtwoorden en andere credentials moeten via environment variables of Portainer secrets geleverd worden.
|
||||
|
||||
---
|
||||
|
||||
## Environment variabelen (voorbeeld)
|
||||
|
||||
Je `docker-compose.yml` verwacht environment variabelen die de database-verbinding en JWT secret definiëren.
|
||||
Maak een local `.env` bestand in de projectroot (NIET commiten). Gebruik deze variabelen als leidraad:
|
||||
|
||||
```
|
||||
# Database (externe Postgres)
|
||||
POSTGRES_HOST=your.db.host.or.ip
|
||||
POSTGRES_PORT=5432
|
||||
POSTGRES_DB=transit_db
|
||||
|
||||
# Per-service DB-credentials (optioneel: kun ook één DB-user gebruiken per DB)
|
||||
POSTGRES_USER_AUTH=auth_user
|
||||
POSTGRES_PASSWORD_AUTH=strong_password_auth
|
||||
POSTGRES_USER_EMPLOYEE=employee_user
|
||||
POSTGRES_PASSWORD_EMPLOYEE=strong_password_employee
|
||||
POSTGRES_USER_TRANSIT=transit_user
|
||||
POSTGRES_PASSWORD_TRANSIT=strong_password_transit
|
||||
|
||||
# JWT secret voor services die JWT gebruiken
|
||||
JWT_SECRET=super_secret_jwt_key_here
|
||||
```
|
||||
|
||||
Opmerking: de exacte variabelen worden gelezen door `docker-compose.yml`. Pas de namen/waarden aan naar jouw omgeving.
|
||||
|
||||
---
|
||||
|
||||
## Lokale ontwikkeling (zonder Docker)
|
||||
|
||||
1. Zorg dat je een PostgreSQL instance hebt draaien (lokal of remote).
|
||||
2. Kopieer per API een `.env` of export de benodigde vars.
|
||||
|
||||
Voorbeeld: run de `auth_api` lokaal
|
||||
|
||||
```bash
|
||||
cd auth_api
|
||||
# installeer dependencies
|
||||
npm install
|
||||
# export env vars (voorbeeld):
|
||||
export DB_HOST=your.db.host
|
||||
export DB_PORT=5432
|
||||
export DB_NAME=transit_db
|
||||
export DB_USER=auth_user
|
||||
export DB_PASSWORD=...
|
||||
export JWT_SECRET=...
|
||||
|
||||
npm start
|
||||
```
|
||||
|
||||
Herhaal voor `employee_api` en `transit_api` met de juiste env keys/poorten.
|
||||
|
||||
Tip: tijdens development kun je één Postgres instance gebruiken en schema/rollen configureren.
|
||||
|
||||
---
|
||||
|
||||
## Docker / Portainer — deployment (met externe Postgres)
|
||||
|
||||
Deze repository bevat `docker-compose.yml` die images vanuit GHCR trekt. De compose is aangepast om een externe Postgres te gebruiken.
|
||||
|
||||
Voordat je start:
|
||||
- Zorg dat je `.env` met database credentials en `JWT_SECRET` klaar staat op de server.
|
||||
- Zorg dat de host waar je compose draait netwerk-connectiviteit heeft naar de Postgres host.
|
||||
|
||||
Stappen om te deployen (server/Portainer host):
|
||||
|
||||
```bash
|
||||
# 1. Zet .env op server (NIET in git)
|
||||
scp .env user@server:/path/to/project/.env
|
||||
# of maak lokaal op de server
|
||||
|
||||
# 2. Login bij GHCR (om private images te kunnen pullen)
|
||||
# Username = je GitHub-gebruikersnaam
|
||||
# Password = PAT met 'write:packages'/'read:packages' scopes of je GITHUB_TOKEN
|
||||
docker login ghcr.io
|
||||
|
||||
# 3. Start stack
|
||||
docker-compose --env-file .env up -d
|
||||
# of met compose V2:
|
||||
docker compose --env-file .env up -d
|
||||
```
|
||||
|
||||
Als je Portainer gebruikt kun je `docker-compose.yml` ook als "Stack" in de Portainer UI plakken en deployment via de UI uitvoeren. Voeg de environment variabelen in Portainer toe of verwijs naar een server-side `.env`.
|
||||
|
||||
Opmerking over `depends_on` in `docker-compose.yml`: omdat je een externe DB gebruikt, verwijst de compose soms nog naar een non-existent `db` service. Je kunt die `depends_on` regels veilig verwijderen of negeren, zolang je database beschikbaar is voordat de services de verbinding proberen te maken.
|
||||
|
||||
---
|
||||
|
||||
## GitHub Actions & Container Registry (CI)
|
||||
|
||||
Het project bevat een workflow in `.github/workflows/docker-build.yml` die bij push naar `main`/`develop` de volgende stappen uitvoert:
|
||||
|
||||
- Checkout
|
||||
- Build Docker images per API (met BuildKit/Buildx)
|
||||
- Login naar de Container Registry (GHCR) en push images
|
||||
- Genereert tags (`latest`, branch/sha, semver als aanwezig)
|
||||
|
||||
Om GHCR te gebruiken op je server:
|
||||
1. Maak een Personal Access Token (PAT) met `read:packages` (en `write:packages` indien je zelf ook wilt pushen).
|
||||
2. Login op de server: `docker login ghcr.io` (gebruik PAT als wachtwoord).
|
||||
|
||||
Image naam voorbeeld:
|
||||
```
|
||||
ghcr.io/<github-username>/<repo>/auth_api:latest
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Health checks, endpoints en debugging
|
||||
|
||||
Enkele nuttige endpoints (voorbeeld):
|
||||
|
||||
- `GET /health` — (beschikbaar in `employee_api`) controleert reachability
|
||||
- `POST /login` — (`auth_api`) authenticatie
|
||||
- `GET /schedule/daily?date=YYYY-MM-DD` — (`transit_api`) vereist auth
|
||||
|
||||
Logs bekijken:
|
||||
|
||||
```bash
|
||||
# Logs van service
|
||||
docker-compose logs -f auth_api
|
||||
|
||||
# Of via container id
|
||||
docker logs -f auth_api
|
||||
```
|
||||
|
||||
Problemen met DB-verbinding:
|
||||
- Controleer netwerkconnectiviteit naar `POSTGRES_HOST`
|
||||
- Controleer users/permissions in Postgres
|
||||
- Controleer dat de juiste schema (zoals `workers`) bestaat als de queries die verwachten
|
||||
|
||||
---
|
||||
|
||||
## Veelvoorkomende taken & commando's
|
||||
|
||||
```bash
|
||||
# Build & run (pull images van GHCR)
|
||||
docker-compose --env-file .env up -d
|
||||
|
||||
# Pull latest images
|
||||
docker-compose pull
|
||||
|
||||
# Recreate containers
|
||||
docker-compose up -d --force-recreate
|
||||
|
||||
# Stop and remove containers
|
||||
docker-compose down
|
||||
|
||||
# Login to GHCR
|
||||
docker login ghcr.io
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migraties & Database schema
|
||||
|
||||
Database schema en migraties zitten niet in deze repository. Zorg dat je:
|
||||
- de juiste schema's (`workers`, `routes`, etc.) aanmaakt
|
||||
- gebruikers en rechten configureert voor de verschillende services
|
||||
|
||||
Als je nog geen database hebt, kun je lokaal een Postgres container gebruiken (development):
|
||||
|
||||
```bash
|
||||
docker run --name transit-db -e POSTGRES_DB=transit_db -e POSTGRES_USER=transit_user -e POSTGRES_PASSWORD=pass -p 5432:5432 -d postgres:15-alpine
|
||||
```
|
||||
|
||||
Maar voor je production/Portainer setup volg je je bestaande beheersbeleid en gebruik je een managed DB of beveiligde host.
|
||||
|
||||
---
|
||||
|
||||
## Deployment tips
|
||||
|
||||
- Gebruik verschillende database users per service met minimale rechten
|
||||
- Gebruik secrets in Portainer of Docker swarm/kubernetes secrets in productie
|
||||
- Gebruik een reverse proxy (nginx, Traefik) voor TLS/HTTPS
|
||||
- Stel log aggregatie en monitoring in (Prometheus/Grafana, ELK, etc.)
|
||||
|
||||
---
|
||||
|
||||
## Contributie
|
||||
|
||||
- Maak feature branches en open pull requests
|
||||
- Push naar `develop` of `main` afhankelijk van je branching policy
|
||||
- CI zal automatisch images bouwen en pushen voor `main`/`develop`
|
||||
|
||||
---
|
||||
|
||||
## Waar te vinden
|
||||
|
||||
- API code: `auth_api/`, `employee_api/`, `transit_api/`
|
||||
- CI workflow: `.github/workflows/docker-build.yml`
|
||||
- Extra docs: `DOCKER_README.md`, `CI_CD_PORTAINER_GUIDE.md`
|
||||
|
||||
|
||||
---
|
||||
|
||||
Als je wilt, kan ik deze README nog aanpassen met specifieke voorbeelden van database schema's of exacte environment-variabele namen voor lokaal draaien. Zeg welke details je wil toevoegen (bijv. example SQL voor `workers` schema).
|
||||
Reference in New Issue
Block a user