From 81924222639bf3f92196e8587329c24df1a00600 Mon Sep 17 00:00:00 2001
From: RaymondVerhoef <raymondverhoef@gmail.com>
Date: Mon, 11 May 2026 20:30:54 +0200
Subject: [PATCH] feat: add production docker-compose configuration and
 deployment documentation for Portainer integration

---
 DEPLOYMENT_GUIDE.md     | 133 ++++++++++++++++++++++++++++++++++++++++
 docker-compose.prod.yml |  37 +++++++++++
 2 files changed, 170 insertions(+)
 create mode 100644 DEPLOYMENT_GUIDE.md
 create mode 100644 docker-compose.prod.yml

diff --git a/DEPLOYMENT_GUIDE.md b/DEPLOYMENT_GUIDE.md
new file mode 100644
index 0000000..36e3866
--- /dev/null
+++ b/DEPLOYMENT_GUIDE.md
@@ -0,0 +1,133 @@
+# 🎯 Overdrachtsdocument – Productie-deployment van **Respellion Learning Platform** met Portainer
+
+> **Doel** – Dit document geeft een *complete* handleiding zodat een ontwikkelaar of AI-agent de Respellion Learning Platform applicatie kan bouwen, configureren en in productie draaien op een Hetzner-VPS via Portainer.
+
+---
+
+## 1. Project-structuur
+
+```
+learning-platform/
+│
+├─ Dockerfile              # Productie Dockerfile (Nginx + React/Vite)
+├─ nginx.conf              # Nginx configuratie voor Anthropic API proxy
+├─ docker-compose.prod.yml # Productie-compose configuratie (Caddy SSL + Frontend)
+└─ src/                    # React frontend broncode
+```
+
+> **Opmerking**: Deze applicatie is een 100% frontend applicatie ("Single Page Application"). De interne state wordt opgeslagen in `localStorage`. Er is **geen externe backend of database (zoals Postgres)** nodig. De enige netwerk calls gaan via de interne Nginx proxy direct naar de Anthropic API.
+
+---
+
+## 2. Kernbestanden – inhoud & rationale
+
+### 2.1 `docker-compose.prod.yml`
+
+```yaml
+services:
+  frontend:
+    build: .
+    restart: always
+    expose:
+      - "80"
+
+  caddy:
+    image: caddy:2-alpine
+    restart: always
+    ports:
+      - "80:80"
+      - "443:443"
+    environment:
+      - DOMAIN_NAME=${DOMAIN_NAME}
+    entrypoint:
+      - /bin/sh
+      - -c
+      - |
+        # Build Caddyfile on container start
+        CLEAN_DOMAIN=$(printf '%s' "$DOMAIN_NAME" | tr -d ';')
+        cat > /etc/caddy/Caddyfile <<EOF
+        ${CLEAN_DOMAIN} {
+            reverse_proxy /* frontend:80
+        }
+        EOF
+        # Run Caddy with the generated file
+        caddy run --config /etc/caddy/Caddyfile --adapter caddyfile
+    volumes:
+      - caddy_data:/data
+      - caddy_config:/config
+    depends_on:
+      - frontend
+
+volumes:
+  caddy_data:
+  caddy_config:
+```
+
+**Belangrijkste punten**
+
+| Item | Waarom |
+|------|--------|
+| **`frontend` (Nginx)** | Bevat de React applicatie en proxy-configuratie voor Anthropic. Exposeert intern poort 80. |
+| **`caddy` (Reverse Proxy)** | Ontvangt alle externe requests op poort 80 en 443 en haalt volautomatisch een SSL Let's Encrypt certificaat op voor `DOMAIN_NAME`. Stuurt verkeer door naar `frontend:80`. |
+| **Volumes `caddy_data/config`** | Slaan de SSL certificaten persistent op zodat Caddy niet bij elke herstart de rate-limits van Let's Encrypt overschrijdt. |
+
+---
+
+### 2.2 `Dockerfile` (Productie)
+
+De applicatie wordt in 2 fasen ("multi-stage") gebouwd:
+1. **Node.js Build:** `npm install` en `npm run build` worden uitgevoerd om de statische Vite applicatie te compileren naar de `dist/` map.
+2. **Nginx Serve:** Een lightweight Nginx Alpine image wordt gestart. Het pakt de `dist/` bestanden en past `nginx.conf` toe om API-aanroepen (CORS blokkades) te omzeilen door als proxy te fungeren.
+
+---
+
+## 3. Omgevingsvariabelen (te definiëren in Portainer)
+
+| Variabele | Voorbeeld | Toelichting |
+|-----------|-----------|-------------|
+| `DOMAIN_NAME` | `leren.mijndomein.nl` | De domeinnaam die Caddy zal beveiligen met HTTPS. Zorg dat je DNS A-record naar je VPS-IP wijst. |
+
+*(De Anthropic API key wordt ingevuld via de instellingen in de applicatie (Settings menu) door een admin, en veilig opgeslagen in localStorage van de gebruiker. Hij hoeft dus niet in Portainer te staan!)*
+
+---
+
+## 4. Deploy-procedure (stap-voor-stap)
+
+### Portainer – stack aanmaken / bijwerken
+
+| Stap | Actie | Details |
+|------|-------|---------|
+| **1** | Navigeer naar **Stacks → + Add stack** | Geef een herkenbare naam (bijv. `respellion-platform`). |
+| **2** | **Repository URL** invullen | `https://github.com/<gebruiker>/learning-platform.git` |
+| **3** | **Compose path** = `docker-compose.prod.yml` | Zorg dat dit exact overeenkomt met de bestandsnaam in de repo. |
+| **4** | **Environment variables** toevoegen | Voeg `DOMAIN_NAME` toe. |
+| **5** | **Deploy the stack** | Portainer start de applicatie en Caddy haalt direct het SSL certificaat op (max. 60 sec). |
+| **6** | **Controle** | Surf naar `https://jouw-domein.nl`. Je zou de Respellion inlogscherm moeten zien. |
+
+### Handmatige Force-Rebuild
+
+Wanneer de repo is geüpdatet en je wil de nieuwe versie afdwingen via command-line:
+
+```bash
+docker compose -f docker-compose.prod.yml up -d --build --no-cache
+```
+
+---
+
+## 5. Veelvoorkomende valkuilen & Fixes
+
+| Symptom | Oorzaak | Oplossing |
+|---------|---------|-----------|
+| **SSL Error / ERR_CONNECTION_REFUSED** | DNS is nog niet actief of poort 443 staat dicht in je firewall (Hetzner). | Check Hetzner Cloud Console en open TCP poort 80 & 443 in de Inbound Firewall. |
+| **Anthropic API Werkt Niet** | Foute key of Nginx proxy mist configuratie. | Open de app, ga naar Admin -> Settings en vul je Anthropic Key in. Controleer ook of `nginx.conf` correct wordt ingeladen in Nginx. |
+| **Witte pagina na deploy** | Oude Docker image wordt gebruikt. | Doe een force-rebuild (`--build --no-cache`) in Portainer of via de console. |
+
+---
+
+## 6. Checklist voor een nieuwe implementatie
+
+- [ ] Repository up-to-date en gepusht naar `main`.
+- [ ] `docker-compose.prod.yml` is gedefinieerd in Portainer.
+- [ ] Environment variable `DOMAIN_NAME` is correct ingesteld.
+- [ ] DNS A-Record staat op de juiste server.
+- [ ] Na eerste inlog: Open "Admin" -> "Settings" en voeg de Anthropic API Key toe, klik op Opslaan.
diff --git a/docker-compose.prod.yml b/docker-compose.prod.yml
new file mode 100644
index 0000000..e98ea7e
--- /dev/null
+++ b/docker-compose.prod.yml
@@ -0,0 +1,37 @@
+services:
+  frontend:
+    build: .
+    restart: always
+    expose:
+      - "80"
+
+  caddy:
+    image: caddy:2-alpine
+    restart: always
+    ports:
+      - "80:80"
+      - "443:443"
+    environment:
+      - DOMAIN_NAME=${DOMAIN_NAME}
+    entrypoint:
+      - /bin/sh
+      - -c
+      - |
+        # Build Caddyfile on container start
+        CLEAN_DOMAIN=$(printf '%s' "$DOMAIN_NAME" | tr -d ';')
+        cat > /etc/caddy/Caddyfile <<EOF
+        ${CLEAN_DOMAIN} {
+            reverse_proxy /* frontend:80
+        }
+        EOF
+        # Run Caddy with the generated file
+        caddy run --config /etc/caddy/Caddyfile --adapter caddyfile
+    volumes:
+      - caddy_data:/data
+      - caddy_config:/config
+    depends_on:
+      - frontend
+
+volumes:
+  caddy_data:
+  caddy_config: