Consolidate documentation and update backend services

- Reorganize docs into 'Core deployment guides' and 'Setup and configuration' subdirectories - Consolidate redundant documentation files (ACR, pipelines, deployment guides) - Add documentation consolidation plan - Update backend database factory and logger services - Update migration script and docker-compose configurations - Add PostgreSQL setup script
2026-01-22 22:45:54 +01:00
parent 18aec4ad80
commit f4399a8e4e
49 changed files with 1320 additions and 7243 deletions
--- a/guides/AZURE-APP-SERVICE-DEPLOYMENT.md
+++ b/guides/AZURE-APP-SERVICE-DEPLOYMENT.md
@@ -0,0 +1,405 @@
+# Azure App Service Deployment - Stap-voor-Stap Guide 🚀
+
+Complete deployment guide voor CMDB Insight naar Azure App Service.
+
+## 🎯 Waarom Azure App Service?
+
+Azure App Service is de aanbevolen deployment optie voor CMDB Insight omdat:
+
+1. **Managed Service** ⭐
+   - Geen serverbeheer, SSH, Linux configuratie nodig
+   - Azure beheert alles (updates, security patches, scaling)
+   - Perfect voor teams die geen infrastructuur willen beheren
+
+2. **Eenvoudig & Snel**
+   - Setup in ~15 minuten
+   - Automatische SSL/TLS certificaten
+   - Integratie met Azure DevOps pipelines
+
+3. **Kosten-Effectief**
+   - Basic B1 plan: ~€15-25/maand
+   - Voldoende voor 20 gebruikers
+   - Geen verborgen kosten
+
+4. **Flexibel**
+   - Deployment slots voor testen (staging → productie)
+   - Eenvoudige rollback
+   - Integratie met Azure Key Vault voor secrets
+
+5. **Monitoring & Compliance**
+   - Integratie met Azure Monitor
+   - Logging en audit trails (NEN 7510 compliance)
+   - Health checks ingebouwd
+
+**Geschatte kosten:** ~€20-25/maand (met PostgreSQL database)
+
+---
+
+## 📋 Prerequisites
+
+- Azure CLI geïnstalleerd en geconfigureerd (`az login`)
+- Docker images in ACR: `zdlasacr.azurecr.io/cmdb-insight/backend:latest` en `frontend:latest`
+- Azure DevOps pipeline werkt (images worden automatisch gebouwd)
+
+---
+
+## 🎯 Quick Start (15 minuten)
+
+### Stap 1: Resource Group
+
+```bash
+az group create \
+  --name zdl-cmdb-insight-prd-euwe-rg \
+  --location westeurope
+```
+
+### Stap 2: App Service Plan
+
+```bash
+az appservice plan create \
+  --name zdl-cmdb-insight-prd-euwe-appsvc \
+  --resource-group zdl-cmdb-insight-prd-euwe-rg \
+  --sku B1 \
+  --is-linux
+```
+
+### Stap 3: Web Apps
+
+```bash
+# Backend
+az webapp create \
+  --name zdl-cmdb-insight-prd-backend-webapp \
+  --resource-group zdl-cmdb-insight-prd-euwe-rg \
+  --plan zdl-cmdb-insight-prd-euwe-appsvc \
+  --container-image-name zdlasacr.azurecr.io/cmdb-insight/backend:latest
+
+# Frontend
+az webapp create \
+  --name zdl-cmdb-insight-prd-frontend-webapp \
+  --resource-group zdl-cmdb-insight-prd-euwe-rg \
+  --plan zdl-cmdb-insight-prd-euwe-appsvc \
+  --container-image-name zdlasacr.azurecr.io/cmdb-insight/frontend:latest
+```
+
+### Stap 4: ACR Authentication
+
+```bash
+# Enable Managed Identity
+az webapp identity assign --name zdl-cmdb-insight-prd-backend-webapp --resource-group zdl-cmdb-insight-prd-euwe-rg
+az webapp identity assign --name zdl-cmdb-insight-prd-frontend-webapp --resource-group zdl-cmdb-insight-prd-euwe-rg
+
+# Get Principal IDs
+BACKEND_PRINCIPAL_ID=$(az webapp identity show \
+  --name zdl-cmdb-insight-prd-backend-webapp \
+  --resource-group zdl-cmdb-insight-prd-euwe-rg \
+  --query principalId -o tsv)
+FRONTEND_PRINCIPAL_ID=$(az webapp identity show \
+  --name zdl-cmdb-insight-prd-frontend-webapp \
+  --resource-group zdl-cmdb-insight-prd-euwe-rg \
+  --query principalId -o tsv)
+
+# Get ACR Resource ID
+ACR_ID=$(az acr show --name zdlasacr --query id -o tsv)
+
+# Grant AcrPull permissions
+az role assignment create --assignee $BACKEND_PRINCIPAL_ID --role AcrPull --scope $ACR_ID
+az role assignment create --assignee $FRONTEND_PRINCIPAL_ID --role AcrPull --scope $ACR_ID
+
+# Configure container settings
+az webapp config container set \
+  --name zdl-cmdb-insight-prd-backend-webapp \
+  --resource-group zdl-cmdb-insight-prd-euwe-rg \
+  --docker-registry-server-url https://zdlasacr.azurecr.io
+
+az webapp config container set \
+  --name zdl-cmdb-insight-prd-frontend-webapp \
+  --resource-group zdl-cmdb-insight-prd-euwe-rg \
+  --docker-registry-server-url https://zdlasacr.azurecr.io
+```
+
+### Stap 5: PostgreSQL Database Setup (Aanbevolen voor Productie)
+
+**Voor PostgreSQL setup, zie:** `docs/AZURE-POSTGRESQL-SETUP.md`
+
+**Quick setup met script:**
+```bash
+./scripts/setup-postgresql.sh
+```
+
+**Of handmatig:**
+```bash
+# Maak PostgreSQL Flexible Server aan
+az postgres flexible-server create \
+  --resource-group zdl-cmdb-insight-prd-euwe-rg \
+  --name zdl-cmdb-insight-prd-psql \
+  --location westeurope \
+  --admin-user cmdbadmin \
+  --admin-password $(openssl rand -base64 32) \
+  --sku-name Standard_B1ms \
+  --tier Burstable \
+  --storage-size 32 \
+  --version 15
+
+# Maak database aan (één database is voldoende)
+az postgres flexible-server db create \
+  --resource-group zdl-cmdb-insight-prd-euwe-rg \
+  --server-name zdl-cmdb-insight-prd-psql \
+  --database-name cmdb_insight
+```
+
+**Voor SQLite (alternatief, eenvoudiger maar minder geschikt voor productie):**
+- Geen extra setup nodig
+- Database wordt automatisch aangemaakt in container
+- Zie Stap 5b hieronder
+
+### Stap 5a: Environment Variabelen met PostgreSQL
+
+```bash
+# Backend met PostgreSQL (vervang met jouw waarden)
+az webapp config appsettings set \
+  --name zdl-cmdb-insight-prd-backend-webapp \
+  --resource-group zdl-cmdb-insight-prd-euwe-rg \
+  --settings \
+    NODE_ENV=production \
+    PORT=3001 \
+    DATABASE_TYPE=postgres \
+    DATABASE_HOST=zdl-cmdb-insight-prd-psql.postgres.database.azure.com \
+    DATABASE_PORT=5432 \
+    DATABASE_NAME=cmdb_insight \
+    DATABASE_USER=cmdbadmin \
+    DATABASE_PASSWORD=your-database-password \
+    DATABASE_SSL=true \
+    JIRA_BASE_URL=https://jira.zuyderland.nl \
+    JIRA_SCHEMA_ID=your-schema-id \
+    JIRA_PAT=your-pat-token \
+    SESSION_SECRET=$(openssl rand -hex 32) \
+    FRONTEND_URL=https://zdl-cmdb-insight-prd-frontend-webapp.azurewebsites.net
+
+# Frontend
+az webapp config appsettings set \
+  --name zdl-cmdb-insight-prd-frontend-webapp \
+  --resource-group zdl-cmdb-insight-prd-euwe-rg \
+  --settings \
+    VITE_API_URL=https://zdl-cmdb-insight-prd-backend-webapp.azurewebsites.net/api
+```
+
+### Stap 5b: Environment Variabelen met SQLite (Alternatief)
+
+```bash
+# Backend met SQLite (vervang met jouw waarden)
+az webapp config appsettings set \
+  --name zdl-cmdb-insight-prd-backend-webapp \
+  --resource-group zdl-cmdb-insight-prd-euwe-rg \
+  --settings \
+    NODE_ENV=production \
+    PORT=3001 \
+    DATABASE_TYPE=sqlite \
+    JIRA_BASE_URL=https://jira.zuyderland.nl \
+    JIRA_SCHEMA_ID=your-schema-id \
+    JIRA_PAT=your-pat-token \
+    SESSION_SECRET=$(openssl rand -hex 32) \
+    FRONTEND_URL=https://zdl-cmdb-insight-prd-frontend-webapp.azurewebsites.net
+
+# Frontend
+az webapp config appsettings set \
+  --name zdl-cmdb-insight-prd-frontend-webapp \
+  --resource-group zdl-cmdb-insight-prd-euwe-rg \
+  --settings \
+    VITE_API_URL=https://zdl-cmdb-insight-prd-backend-webapp.azurewebsites.net/api
+```
+
+### Stap 6: Start Apps
+
+```bash
+az webapp start --name zdl-cmdb-insight-prd-backend-webapp --resource-group zdl-cmdb-insight-prd-euwe-rg
+az webapp start --name zdl-cmdb-insight-prd-frontend-webapp --resource-group zdl-cmdb-insight-prd-euwe-rg
+```
+
+### Stap 7: Test
+
+```bash
+# Health check
+curl https://zdl-cmdb-insight-prd-backend-webapp.azurewebsites.net/api/health
+
+# Frontend
+curl https://zdl-cmdb-insight-prd-frontend-webapp.azurewebsites.net
+```
+
+**🎉 Je applicatie is nu live!**
+
+- Frontend: `https://zdl-cmdb-insight-prd-frontend-webapp.azurewebsites.net`
+- Backend API: `https://zdl-cmdb-insight-prd-backend-webapp.azurewebsites.net/api`
+
+---
+
+## 🔐 Azure Key Vault Setup (Aanbevolen)
+
+Voor productie: gebruik Azure Key Vault voor secrets.
+
+### Stap 1: Key Vault Aanmaken
+
+```bash
+az keyvault create \
+  --name kv-cmdb-insight-prod \
+  --resource-group zdl-cmdb-insight-prd-euwe-rg \
+  --location westeurope \
+  --sku standard
+```
+
+### Stap 2: Secrets Toevoegen
+
+```bash
+az keyvault secret set --vault-name kv-cmdb-insight-prod --name JiraPat --value "your-token"
+az keyvault secret set --vault-name kv-cmdb-insight-prod --name SessionSecret --value "$(openssl rand -hex 32)"
+az keyvault secret set --vault-name kv-cmdb-insight-prod --name JiraSchemaId --value "your-schema-id"
+```
+
+### Stap 3: Grant Access
+
+**Voor Key Vault met RBAC authorization (aanbevolen):**
+
+```bash
+# Get Key Vault Resource ID
+KV_ID=$(az keyvault show --name zdl-cmdb-insight-prd-kv --query id -o tsv)
+
+# Grant Key Vault Secrets User role to backend
+az role assignment create \
+  --assignee $BACKEND_PRINCIPAL_ID \
+  --role "Key Vault Secrets User" \
+  --scope $KV_ID
+
+# Grant to frontend (if needed)
+az role assignment create \
+  --assignee $FRONTEND_PRINCIPAL_ID \
+  --role "Key Vault Secrets User" \
+  --scope $KV_ID
+```
+
+**Voor Key Vault met Access Policies (oude methode):**
+
+```bash
+az keyvault set-policy \
+  --name zdl-cmdb-insight-prd-kv \
+  --object-id $BACKEND_PRINCIPAL_ID \
+  --secret-permissions get list
+```
+
+**Let op:** Als je de fout krijgt "Cannot set policies to a vault with '--enable-rbac-authorization'", gebruik dan de RBAC methode hierboven.
+
+### Stap 4: Configure App Settings met Key Vault References
+
+```bash
+az webapp config appsettings set \
+  --name zdl-cmdb-insight-prd-backend-webapp \
+  --resource-group zdl-cmdb-insight-prd-euwe-rg \
+  --settings \
+    JIRA_PAT="@Microsoft.KeyVault(SecretUri=https://kv-cmdb-insight-prod.vault.azure.net/secrets/JiraPat/)" \
+    SESSION_SECRET="@Microsoft.KeyVault(SecretUri=https://kv-cmdb-insight-prod.vault.azure.net/secrets/SessionSecret/)" \
+    JIRA_SCHEMA_ID="@Microsoft.KeyVault(SecretUri=https://kv-cmdb-insight-prod.vault.azure.net/secrets/JiraSchemaId/)"
+```
+
+---
+
+## 📊 Monitoring Setup
+
+### Application Insights
+
+```bash
+# Create Application Insights
+az monitor app-insights component create \
+  --app cmdb-insight-prod \
+  --location westeurope \
+  --resource-group zdl-cmdb-insight-prd-euwe-rg \
+  --application-type web
+
+# Get Instrumentation Key
+INSTRUMENTATION_KEY=$(az monitor app-insights component show \
+  --app cmdb-insight-prod \
+  --resource-group zdl-cmdb-insight-prd-euwe-rg \
+  --query instrumentationKey -o tsv)
+
+# Configure App Settings
+az webapp config appsettings set \
+  --name zdl-cmdb-insight-prd-backend-webapp \
+  --resource-group zdl-cmdb-insight-prd-euwe-rg \
+  --settings \
+    APPINSIGHTS_INSTRUMENTATIONKEY=$INSTRUMENTATION_KEY
+```
+
+---
+
+## 🔄 Updates Deployen
+
+### Optie 1: Manual (Eenvoudig)
+
+```bash
+# Restart Web Apps (pull nieuwe latest image)
+az webapp restart --name zdl-cmdb-insight-prd-backend-webapp --resource-group zdl-cmdb-insight-prd-euwe-rg
+az webapp restart --name zdl-cmdb-insight-prd-frontend-webapp --resource-group zdl-cmdb-insight-prd-euwe-rg
+```
+
+### Optie 2: Deployment Slots (Zero-Downtime)
+
+```bash
+# Create staging slot
+az webapp deployment slot create \
+  --name zdl-cmdb-insight-prd-backend-webapp \
+  --resource-group zdl-cmdb-insight-prd-euwe-rg \
+  --slot staging
+
+# Deploy to staging
+az webapp deployment slot swap \
+  --name zdl-cmdb-insight-prd-backend-webapp \
+  --resource-group zdl-cmdb-insight-prd-euwe-rg \
+  --slot staging \
+  --target-slot production
+```
+
+---
+
+## 🛠️ Troubleshooting
+
+### Check Logs
+
+```bash
+# Live logs
+az webapp log tail --name zdl-cmdb-insight-prd-backend-webapp --resource-group zdl-cmdb-insight-prd-euwe-rg
+
+# Download logs
+az webapp log download --name zdl-cmdb-insight-prd-backend-webapp --resource-group zdl-cmdb-insight-prd-euwe-rg --log-file logs.zip
+```
+
+### Check Status
+
+```bash
+az webapp show --name zdl-cmdb-insight-prd-backend-webapp --resource-group zdl-cmdb-insight-prd-euwe-rg --query state
+```
+
+### Restart App
+
+```bash
+az webapp restart --name zdl-cmdb-insight-prd-backend-webapp --resource-group zdl-cmdb-insight-prd-euwe-rg
+```
+
+---
+
+## 📚 Meer Informatie
+
+- **Quick Reference**: `docs/AZURE-QUICK-REFERENCE.md`
+- **Production Deployment**: `docs/PRODUCTION-DEPLOYMENT.md`
+
+---
+
+## ✅ Checklist
+
+- [ ] Resource Group aangemaakt
+- [ ] App Service Plan aangemaakt
+- [ ] Web Apps aangemaakt
+- [ ] ACR authentication geconfigureerd
+- [ ] Environment variabelen ingesteld
+- [ ] Key Vault geconfigureerd (optioneel)
+- [ ] Application Insights ingeschakeld
+- [ ] Health checks werken
+- [ ] Team geïnformeerd
+
+**Veel succes! 🚀**