Belangrijk: deze README bevat geen wachtwoorden of andere gevoelige gegevens. Sla secrets altijd buiten versiebeheer op (environment variables, secret managers, Portainer secrets, etc.).

Security & Private Files

⚠️ Important: This repository excludes private documentation and setup instructions from Git and Docker builds. See SECURITY_PRIVATE_FILES.md for details on:

What files are kept private and why
How .gitignore and .dockerignore protect sensitive information
Best practices for handling deployment documentation
Guidelines for adding new private files

Private files are excluded (not in git/docker):

GETTING_STARTED.md - Internal setup guide
ADMIN_DEPLOYMENT_SUMMARY.md - Deployment status
CI_CD_PORTAINER_GUIDE.md - Infrastructure docs
DEPLOYMENT.md - Deployment procedures
Custom instruction files (.instructions.md, 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)

Zorg dat je een PostgreSQL instance hebt draaien (lokal of remote).
Kopieer per API een .env of export de benodigde vars.

Voorbeeld: run de auth_api lokaal

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):

# 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:

Maak een Personal Access Token (PAT) met read:packages (en write:packages indien je zelf ook wilt pushen).
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:

# 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

# 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):

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

Admin Control Center

The project includes a modern React admin dashboard for fleet and schedule management.

Features

Fleet Management: Create and manage buses with seat capacity and license plates
Transit Lines: Define bus routes with start/end stops and duration
Route Management: Link stops to bus lines with drag-and-drop reordering
Schedule Maker: Create schedules by assigning vehicles and crew to bus lines with time slots
Timetable View: 24-hour timetable showing scheduled services
Delete Operations: Remove stops, lines, and schedules with confirmation modals

Admin UI Location

admin_ui/
├── src/
│   ├── components/
│   │   ├── StopsManager.jsx      # Create and manage transit stops
│   │   ├── BusLinesManager.jsx   # Manage bus lines and routes
│   │   ├── FleetManager.jsx      # Manage fleet vehicles
│   │   ├── LinkStop.jsx          # Drag-drop route stop assignment
│   │   ├── ScheduleMaker.jsx     # Create and manage schedules
│   │   ├── TimetableViewer.jsx   # Public timetable (reusable)
│   │   └── Login.jsx             # Admin authentication
│   ├── App.jsx                   # Main app component
│   ├── api.js                    # API client with runtime config
│   └── styles.css                # Responsive UI styling
├── docker-entrypoint.sh          # Runtime env config
└── Dockerfile                    # Multi-stage build

Building the Admin UI

cd admin_ui
npm install
npm run build         # Production build
npm run dev          # Development (Vite)

Docker Deployment

The admin UI is included in docker-compose.yml as service admin_ui on port 5174.

docker-compose up admin_ui
# Access at http://localhost:5174

Public Schedule API

The Transit API exposes public (unauthenticated) schedule endpoints:

Endpoints:

GET /schedules?date=YYYY-MM-DD&lineId=ID — Get schedules for a date/line
GET /schedules/:scheduleId — Get schedule details
GET /schedules/:scheduleId/stops — Get stops on a schedule's line

Example:

curl http://localhost:5001/schedules?date=2026-05-06

TimetableViewer Component:

import TimetableViewer from './components/TimetableViewer'

<TimetableViewer apiBaseUrl="http://api.transit.local:5001" />

Schedule Maker Documentation

See admin_ui/SCHEDULE_API.md for detailed API documentation, usage examples, and UI features.

Authentication

Admin dashboard uses simple JWT-based authentication:

Login with user code (e.g., 42)
Receive JWT token from auth_api
Use token for admin operations (/admin/* endpoints)

Admin authorization is controlled by ADMIN_USER_CODES environment variable:

ADMIN_USER_CODES=42,101,205  # Comma-separated admin user codes

Development vs Production

Development Mode

Use DEV_MOCK=1 to work without a database (in-memory mock storage):

ADMIN_USER_CODES=42 DEV_MOCK=1 JWT_SECRET=devsecret npm --prefix ./transit_api start

Production Mode

Set up real PostgreSQL database and provide credentials via environment variables.

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).

Languages

JavaScript 52.3%

Dart 34.6%

C++ 5.1%

CMake 4%

CSS 1.3%

Other 2.7%