Implementatie & Deployment Guide

Een kleine User Manual voor het opzetten, deployen en onderhouden van het Fire Management System (FMS).

1. Project Overzicht

Het Fire Management System is een moderne web-applicatie voor het in kaart brengen van natuurbranden in België. Het systeem bestaat uit drie onderdelen:

Frontend Monorepo: Vue 3 + Nuxt 3 Applicaties (Admin-Portal & Viewer).
Backend: Node.js/Express API met TypeScript.
Database: PostgreSQL (PostGIS) met Containerized Setup.

Architectuur

┌─────────────────────────────────────────────────────────┐
│                    User Interfaces                      │
│     AdminPortal        │        UserDashboard           │
│    (Vue 3 + Nuxt)      │       (Vue 3 + Nuxt)           │
└──────────────┬─────────┴────────────────┬───────────────┘
               │                          │
               └──────────────┬───────────┘
                              │
                    ┌─────────▼─────────┐
                    │   Backend API     │
                    │ (Node + Express)  │
                    └─────────┬─────────┘
                              │
                    ┌─────────▼─────────┐
                    │   PostgreSQL      │
                    │    Database       │
                    └───────────────────┘

2. Tech Stack

Frontend

Vue 3 - Progressive JavaScript Framework
Nuxt 3 - Vue Framework met File-based Routing
TypeScript - Type-safe JavaScript
Pinia - State Management
Vitepress - Documentation Site
pnpm - Package Manager (Monorepo Support)

Backend

Node.js - JavaScript Runtime
Express - Web Framework
TypeScript - Type-safe Backend
PostgreSQL - Relationele Database
Docker - Containerization

Development Tools

Vitest - Unit Testing Framework
ESLint - Code Quality Checks
Git - Version Control

3. Vereisten

Development Omgeving

Node.js versie 18.0.0 of hoger
pnpm versie 8.0 of hoger (installeer met: npm install -g pnpm)
Git versie 2.30+
Docker en Docker Compose (voor database)
Minimaal 8GB RAM en 10GB vrije schijfruimte

Production Omgeving

Server met minimaal 2vCPU, 4GB RAM, 20GB opslag
Ubuntu 20.04 LTS of vergelijkbaar Linux
Docker en Docker Compose
HTTPS certificaat (Let's Encrypt aanbevolen)
Domeinaam gereserveerd

4. Installatie en Setup

4.1 Development Omgeving Opzetten

Stap 1: Repository Klonen

bash

git clone <repository-url>
cd frontend-monorepo
cd backend
# Beide directories hebben aparte setup

Stap 2: Afhankelijkheden Installeren

bash

# Frontend
cd frontend-monorepo
pnpm install

# Backend
cd ../backend/back-end/project/containers/backend
pnpm install

Stap 3: Database Starten

bash

# In backend/back-end/project/containers/
docker-compose up -d db

# Wacht totdat PostgreSQL volledig gestart is (30-60 seconden)
docker logs db  # Controleer logs

Stap 4: Database Initialiseren

bash

# Migrations runnen
cd backend/back-end/project/containers/backend
pnpm run migrate:latest
# Of handmatig de init.sql uitvoeren

Stap 5: Environment Variabelen Configureren

bash

# Backend - maak .env file
cd backend/back-end/project/containers/backend
cat > .env << EOF
NODE_ENV=development
DB_HOST=localhost
DB_PORT=5432
DB_NAME=fire_management
DB_USER=postgres
DB_PASSWORD=postgres
JWT_SECRET=your-secret-key-here
API_PORT=3000
CORS_ORIGIN=http://localhost:3000
EOF

# Frontend - maak .env file (in frontend-monorepo)
cat > .env.development << EOF
VITE_API_URL=http://localhost:3000
VITE_APP_TITLE=Fire Management System
EOF

Stap 6: Applicaties Starten

bash

# Terminal 1 - Backend
cd backend/back-end/project/containers/backend
pnpm run dev
# Server draait op http://localhost:3000

# Terminal 2 - Frontend AdminPortal
cd frontend-monorepo
pnpm run dev -w adminportal
# App beschikbaar op http://localhost:3001

# Terminal 3 - Frontend UserDashboard
cd frontend-monorepo
pnpm run dev -w userdashboard
# App beschikbaar op http://localhost:3002

# Terminal 4 - Documentatie (optioneel)
cd frontend-monorepo
pnpm run docs:dev
# Docs beschikbaar op http://localhost:5173

4.2 Database Configuratie

PostgreSQL Initialisatie

De database wordt automatisch geinitialiseerd via Docker. Het schema bevat:

users - Gebruikersaccounts
fires - Brandmeldingen
fire_details - Detailinformatie per brand
locations - Locatiegegevens
roles - Gebruikersrollen

Backup & Restore

bash

# Backup maken
docker exec db pg_dump -U postgres fire_management > backup.sql

# Backup herstellen
cat backup.sql | docker exec -i db psql -U postgres fire_management

5. Configuratie

5.1 Backend Configuratie

Essentiële Environment Variabelen:

NODE_ENV          = development|staging|production
DB_HOST          = Database host (localhost of server IP)
DB_PORT          = Database port (standaard 5432)
DB_NAME          = Database naam
DB_USER          = Database gebruiker
DB_PASSWORD      = Database wachtwoord
JWT_SECRET       = Geheim voor JWT-tokens (WIJZIG IN PRODUCTION!)
API_PORT         = API server port (standaard 3000)
CORS_ORIGIN      = Allowed frontend origin
LOG_LEVEL        = debug|info|warn|error

5.2 Frontend Configuratie

AdminPortal (adminportal/.env):

VITE_API_URL     = Backend API URL
VITE_APP_TITLE   = Applicatietitel
VITE_LOG_LEVEL   = debug|info|warn|error

UserDashboard (userdashboard/.env):

VITE_API_URL     = Backend API URL
VITE_APP_TITLE   = Applicatietitel

5.3 Docker Compose Configuratie

Het systeem gebruikt Docker containers voor isolatie:

Services:

backend - Node.js applicatie
db - PostgreSQL database
nginx - Reverse proxy (production only)

Poorten:

Backend API: 3000
AdminPortal: 3001
UserDashboard: 3002
PostgreSQL: 5432
Nginx: 80, 443

6. Build & Deployment

6.1 Production Build Maken

bash

# Frontend builds
cd frontend-monorepo
pnpm run build

# Output in dist/
# - dist/adminportal/ (AdminPortal)
# - dist/userdashboard/ (UserDashboard)

# Backend build
cd backend/back-end/project/containers/backend
pnpm run build

# Output in dist/

6.2 Docker Containers Bouwen

bash

# Backend image bouwen
cd backend/back-end/project/containers/backend
docker build -t fms-backend:latest -f Dockerfile.production .

# Database image voorgeconfigureerd in docker-compose.yml

# Frontend kan geserved worden via Nginx of aparte Node container

6.3 Production Deployment

Optie 1: Docker Compose (Aanbevolen voor kleine deployments)

bash

# In de root folder met docker-compose.yml
docker-compose -f docker-compose.yml up -d

# Controleer status
docker-compose ps
docker-compose logs -f backend

# Stop deployment
docker-compose down

Optie 2: Kubernetes (Voor schaalbare deployments)

Zie docs/guide/kubernetes.md voor volledige K8s configuratie.

Optie 3: Traditionele Server Deployment

bash

# 1. Dependencies installeren
sudo apt-get update
sudo apt-get install -y nodejs npm postgresql

# 2. Applicatie klonen en dependencies installeren
git clone <repo> /opt/fms
cd /opt/fms
npm install

# 3. Database configureren
sudo -u postgres createdb fire_management
sudo -u postgres psql fire_management < db/init.sql

# 4. PM2 starten
npm install -g pm2
pm2 start backend/server.js --name "fms-backend"
pm2 start build/index.js --name "fms-frontend"

# 5. Systemd service configureren
# Zie templates in deployment/systemd/

7. Hosting Opties

7.1 AWS (Amazon Web Services)

Kosten (geschat per maand):

EC2 t3.medium: €35
RDS PostgreSQL db.t3.micro: €30
Load Balancer: €20
Data Transfer: €5-15
Totaal: ~€90-115/maand

Setup:

EC2 instance starten (Ubuntu 20.04)
RDS PostgreSQL instance maken
Security Groups configureren
Elastic IP koppelen
Application deployen via CI/CD

Voordelen:

Hoog schaalbaar
Global infrastructure
Managed services beschikbaar

7.2 DigitalOcean

Kosten (geschat per maand):

Droplet ($5/maand voor test): €5
Droplet ($12-24/maand voor productie): €12-24
Managed Database: €15-30
Backups: €3-5
Totaal: ~€35-60/maand

Setup:

Droplet aanmaken
Docker installeren
docker-compose.yml deployen
Managed Database koppelen
Nginx/Certbot configureren

Voordelen:

Eenvoudiger dan AWS
Betaalde support beschikbaar
Goede prijs/prestatie

7.3 Azure

Kosten (geschat per maand):

App Service plan: €15-50
Azure Database PostgreSQL: €30-80
Storage: €5
Totaal: ~€50-135/maand

Setup:

Resource Group aanmaken
App Service deployen
Database configureren
CI/CD pipeline instellen
Custom domain configureren

Voordelen:

Enterprise support
Goede integratie met Microsoft tools
Hybrid cloud capable

7.4 Lokale/On-Premise Server

Eenmalige kosten:

Server hardware: €500-2000
Network setup: €500-1000
Software licenties: €0 (open source)
Totaal: €1000-3000

Maandelijkse kosten:

Elektriciteit: €50-100
Internet/bandwidth: €50-200
Maintenance: €100/uur (externe support)

Setup:

Server hardware aanschaffen
Linux installeren
Docker en applicatie deployen
Backup systeem configureren
Firewall en beveiliging instellen

Voordelen:

Volledige controle
Geen cloud-afhankelijkheid
Hogere latency in sommige gebieden

Aanbeveling

Voor de initiale launch: DigitalOcean of AWS vanwege balans tussen kosten en betrouwbaarheid.

8. Startup Procedure

8.1 Eerste Keer Starten (Fresh Deployment)

bash

# 1. SSH in de server
ssh ubuntu@your-server-ip

# 2. Repository klonen
git clone <repo-url> /opt/fms
cd /opt/fms

# 3. Secrets configureren
mkdir -p secrets
echo "your-jwt-secret" > secrets/jwt.secret
echo "db-password" > secrets/db.password
chmod 600 secrets/*

# 4. Database initialiseren
docker-compose up -d db
sleep 30  # Wacht op database startup
docker-compose exec db psql -U postgres -f /docker-entrypoint-initdb.d/init.sql

# 5. Containers starten
docker-compose up -d

# 6. Health checks
curl http://localhost:3000/health
curl http://localhost:3001/

8.2 Server Herstarten

bash

# Graceful shutdown
docker-compose down

# Start opnieuw
docker-compose up -d

# Controleer logs
docker-compose logs -f

8.3 Updates & Patches

bash

# Code updates
cd /opt/fms
git pull origin main

# Docker images herbouwen
docker-compose down
docker-compose build --no-cache
docker-compose up -d

# Database migrations uitvoeren
docker-compose exec backend npm run migrate:latest

# Controleer status
docker-compose ps

9. Monitoring & Maintenance

9.1 Logbestanden

bash

# Backend logs
docker-compose logs backend

# Database logs
docker-compose logs db

# Alle logs volgen
docker-compose logs -f

# Logs in bestanden opslaan
docker-compose logs backend > logs/backend.log 2>&1

9.2 Performance Monitoring

CPU/Memory Usage:

bash

docker stats

Database Performance:

bash

docker-compose exec db psql -U postgres fire_management
# EXPLAIN ANALYZE <query>;
# \dt  -- List tables
# \di  -- List indexes

9.3 Backups

Dagelijks Backup:

bash

#!/bin/bash
DATE=$(date +%Y-%m-%d_%H-%M-%S)
docker-compose exec -T db pg_dump -U postgres fire_management | gzip > backups/fire_management_$DATE.sql.gz

# Behoud 30 dagen backups
find backups/ -name "*.sql.gz" -mtime +30 -delete

Backup naar Cloud:

bash

# Backup naar S3 (AWS)
aws s3 cp backups/fire_management_latest.sql.gz s3://your-bucket/backups/

# Backup naar Azure
az storage blob upload --file backups/fire_management_latest.sql.gz --container-name backups

9.4 Health Checks

bash

# Backend health
curl -X GET http://localhost:3000/health

# Database connectivity
docker-compose exec backend npm run check:db

# Frontend status (via browser)
curl -I http://localhost:3001/

10. Security

10.1 Environment Secrets

NOOIT in git committen:

bash

# Wijzig alle standard waarden!
JWT_SECRET                    # Genereer met: openssl rand -hex 32
DB_PASSWORD                   # Minimaal 12 characters
ADMIN_PASSWORD               # Minimaal 12 characters
API_KEY                      # Indien van toepassing

10.2 Database Security

sql

-- Versterkt gebruikersbeleid
ALTER ROLE postgres WITH PASSWORD 'strong-password-here';
CREATE ROLE app_user WITH LOGIN PASSWORD 'strong-password';
GRANT CONNECT ON DATABASE fire_management TO app_user;
GRANT USAGE ON SCHEMA public TO app_user;
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO app_user;

10.3 Firewall Configuratie

UFW (Ubuntu Firewall):

bash

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp       # SSH
sudo ufw allow 80/tcp       # HTTP
sudo ufw allow 443/tcp      # HTTPS
sudo ufw enable

AWS Security Group:

Inbound: TCP 22 (SSH), 80 (HTTP), 443 (HTTPS)
Outbound: All traffic allowed
Database: Only from application server

10.4 SSL/TLS Certificaten

Let's Encrypt met Certbot:

bash

sudo apt-get install certbot python3-certbot-nginx

sudo certbot certonly --standalone -d yourdomain.com

# Configureer auto-renewal
sudo systemctl enable certbot.timer

10.5 CORS Configuratie

Backend CORS settings in .env:

CORS_ORIGIN=https://yourdomain.com,https://www.yourdomain.com

11. Troubleshooting

11.1 Database Connection Errors

Error: "connect ECONNREFUSED 127.0.0.1:5432"

Oplossing:

bash

# Controleer database status
docker-compose ps db

# Restart database
docker-compose restart db

# Controleer logs
docker-compose logs db

11.2 Memory Leaks

Symptoom: Memory usage stijgt voortdurend

Oplossing:

bash

# Controleer huige processen
docker stats

# Restart container
docker-compose restart backend

# Check Node.js heap
docker-compose exec backend node -e "console.log(process.memoryUsage())"

11.3 Slow Queries

Diagnose:

bash

# PostgreSQL query log
docker-compose exec db psql -U postgres fire_management
> SET log_min_duration_statement = 1000;  -- Log queries > 1 sec
> SELECT * FROM pg_stat_statements ORDER BY mean_time DESC LIMIT 10;

11.4 Deployment Failure

Controleer stappen:

Docker images beschikbaar: docker images
Poorten niet in gebruik: netstat -tulpn | grep LISTEN
Disk space beschikbaar: df -h /
RAM beschikbaar: free -h
Logs controleren: docker-compose logs

12. Escalatie & Support

12.1 Error Handling Workflow

Level 1 - Automatisch:

Application logs
Email alerts
Slack notifications

Level 2 - Support Team:

SSH diagnostiek
Database queries
Service restarts

Level 3 - Development Team:

Code debugging
Architecture changes
Database migrations

12.2 Contact Informatie

Development Team: [email] Operations Team: [email] Emergency Hotline: [telefoonnummer]

12.3 Service Level Agreement (SLA)

Uptime Target: 99.5% per maand
Response Time: <1 uur voor kritieke issues
Resolution Time: <4 uren voor kritieke issues
Planned Maintenance: Maandelijks op zondagnacht 22:00-23:00

13. Gebruikershandleiding voor Operatoren

13.1 Dagelijks

Controleer system health dashboard
Controleer error logs
Verifieer database backups zijn gemaakt
Controleer disk space (minimum 10% vrij)

13.2 Wekelijks

Review performance metrics
Controleer update beschikbaarheid
Test backup/restore procedure
Verifieer monitoring alerts

13.3 Maandelijks

Security updates installeren
Database maintenance uitvoeren (VACUUM, ANALYZE)
Full system backup naar externe locatie
Capacity planning review

14. Handover Checklist

Voor overdracht aan operations team:

Alle environment variables gedocumenteerd
Database backups ingesteld en getest
Monitoring en alerting geconfigureerd
Runbook voor veelvoorkomende issues
Support contact informatie beschikbaar
Access credentials veilig overhandigd
Training sessie gehouden
Documentation up-to-date

Laatst bijgewerkt: 2025-01-07 Document versie: 1.0 Onderhoudstatus: Actief

Implementatie & Deployment Guide ​

1. Project Overzicht ​

Architectuur ​

2. Tech Stack ​

Frontend ​

Backend ​

Development Tools ​

3. Vereisten ​

Development Omgeving ​

Production Omgeving ​

4. Installatie en Setup ​

4.1 Development Omgeving Opzetten ​

Stap 1: Repository Klonen ​

Stap 2: Afhankelijkheden Installeren ​

Stap 3: Database Starten ​

Stap 4: Database Initialiseren ​

Stap 5: Environment Variabelen Configureren ​

Stap 6: Applicaties Starten ​

4.2 Database Configuratie ​

PostgreSQL Initialisatie ​

Backup & Restore ​

5. Configuratie ​

5.1 Backend Configuratie ​

5.2 Frontend Configuratie ​

5.3 Docker Compose Configuratie ​

6. Build & Deployment ​

6.1 Production Build Maken ​

6.2 Docker Containers Bouwen ​

6.3 Production Deployment ​

Optie 1: Docker Compose (Aanbevolen voor kleine deployments) ​

Optie 2: Kubernetes (Voor schaalbare deployments) ​

Optie 3: Traditionele Server Deployment ​

7. Hosting Opties ​

7.1 AWS (Amazon Web Services) ​

7.2 DigitalOcean ​

7.3 Azure ​

7.4 Lokale/On-Premise Server ​

Aanbeveling ​

8. Startup Procedure ​

8.1 Eerste Keer Starten (Fresh Deployment) ​

8.2 Server Herstarten ​

8.3 Updates & Patches ​

9. Monitoring & Maintenance ​

9.1 Logbestanden ​

9.2 Performance Monitoring ​

9.3 Backups ​

9.4 Health Checks ​

10. Security ​

10.1 Environment Secrets ​

10.2 Database Security ​

10.3 Firewall Configuratie ​

10.4 SSL/TLS Certificaten ​

10.5 CORS Configuratie ​

11. Troubleshooting ​

11.1 Database Connection Errors ​

11.2 Memory Leaks ​

11.3 Slow Queries ​

11.4 Deployment Failure ​

12. Escalatie & Support ​

12.1 Error Handling Workflow ​

12.2 Contact Informatie ​

12.3 Service Level Agreement (SLA) ​

13. Gebruikershandleiding voor Operatoren ​

13.1 Dagelijks ​

13.2 Wekelijks ​

13.3 Maandelijks ​

14. Handover Checklist ​

Implementatie & Deployment Guide

1. Project Overzicht

Architectuur

2. Tech Stack

Frontend

Backend

Development Tools

3. Vereisten

Development Omgeving

Production Omgeving

4. Installatie en Setup

4.1 Development Omgeving Opzetten

Stap 1: Repository Klonen

Stap 2: Afhankelijkheden Installeren

Stap 3: Database Starten

Stap 4: Database Initialiseren

Stap 5: Environment Variabelen Configureren

Stap 6: Applicaties Starten

4.2 Database Configuratie

PostgreSQL Initialisatie

Backup & Restore

5. Configuratie

5.1 Backend Configuratie

5.2 Frontend Configuratie

5.3 Docker Compose Configuratie

6. Build & Deployment

6.1 Production Build Maken

6.2 Docker Containers Bouwen

6.3 Production Deployment

Optie 1: Docker Compose (Aanbevolen voor kleine deployments)

Optie 2: Kubernetes (Voor schaalbare deployments)

Optie 3: Traditionele Server Deployment

7. Hosting Opties

7.1 AWS (Amazon Web Services)

7.2 DigitalOcean

7.3 Azure

7.4 Lokale/On-Premise Server

Aanbeveling

8. Startup Procedure

8.1 Eerste Keer Starten (Fresh Deployment)

8.2 Server Herstarten

8.3 Updates & Patches

9. Monitoring & Maintenance

9.1 Logbestanden

9.2 Performance Monitoring

9.3 Backups

9.4 Health Checks

10. Security

10.1 Environment Secrets

10.2 Database Security

10.3 Firewall Configuratie

10.4 SSL/TLS Certificaten

10.5 CORS Configuratie

11. Troubleshooting

11.1 Database Connection Errors

11.2 Memory Leaks

11.3 Slow Queries

11.4 Deployment Failure

12. Escalatie & Support

12.1 Error Handling Workflow

12.2 Contact Informatie

12.3 Service Level Agreement (SLA)

13. Gebruikershandleiding voor Operatoren

13.1 Dagelijks

13.2 Wekelijks

13.3 Maandelijks

14. Handover Checklist