From 02ecca7598c3fe210efebd3168e71d5b2fa013f0 Mon Sep 17 00:00:00 2001
From: Joey Yakimowich-Payne <jyapayne@pm.me>
Date: Thu, 15 Jan 2026 22:21:52 -0700
Subject: [PATCH] Add docs

---
 docs/PRODUCTION.md | 52 ++++++++++++++++++++--------------------------
 1 file changed, 22 insertions(+), 30 deletions(-)

diff --git a/docs/PRODUCTION.md b/docs/PRODUCTION.md
index d9670c3..f9217d6 100644
--- a/docs/PRODUCTION.md
+++ b/docs/PRODUCTION.md
@@ -16,11 +16,10 @@ The easiest way to deploy Kaboot is using the automated setup script:
 
 This script automatically:
 - Generates all required secrets (database passwords, API tokens, etc.)
-- Creates the production `.env` file
+- Creates the production `.env` file with domain configuration
 - Creates the `Caddyfile` with your domains
 - Creates the Authentik production blueprint
 - Removes the development blueprint
-- Builds the frontend with production URLs
 
 After running the script, start the stack:
 
@@ -67,19 +66,16 @@ cp Caddyfile.example Caddyfile
 # Edit Caddyfile - replace example.com with your domains
 
 # 4. Update .env with production values
+#    - KABOOT_DOMAIN=your-app.com
+#    - AUTH_DOMAIN=auth.your-app.com
 #    - OIDC_ISSUER=https://auth.your-app.com/application/o/kaboot/
 #    - OIDC_JWKS_URI=https://auth.your-app.com/application/o/kaboot/jwks/
 #    - CORS_ORIGIN=https://your-app.com
 
-# 5. Build frontend with production URLs
-VITE_API_URL=https://your-app.com/api \
-VITE_OIDC_AUTHORITY=https://auth.your-app.com/application/o/kaboot/ \
-npm run build
+# 5. Start the stack (frontend builds automatically in Docker)
+docker compose -f docker-compose.prod.yml -f docker-compose.caddy.yml up -d --build
 
-# 6. Start the stack
-docker compose -f docker-compose.prod.yml -f docker-compose.caddy.yml up -d
-
-# 7. Verify
+# 6. Verify
 docker compose -f docker-compose.prod.yml -f docker-compose.caddy.yml ps
 ```
 
@@ -90,6 +86,8 @@ docker compose -f docker-compose.prod.yml -f docker-compose.caddy.yml ps
 -   DNS A records pointing your domains to your server (see below).
 -   A Google Gemini API key (optional, for AI quiz generation).
 
+> **Note**: Node.js is **not** required on the production server. The frontend is built inside a Docker container.
+
 ## DNS Configuration
 
 You need two DNS records pointing to your server's IP address. You can use either:
@@ -159,10 +157,9 @@ Both should return your server's IP address. You can also use [dnschecker.org](h
 ## Architecture Overview
 
 In production, the stack consists of:
--   **Caddy**: Reverse proxy with automatic HTTPS via Let's Encrypt.
--   **Authentik**: Identity Provider for OAuth2/OIDC authentication.
+-   **Kaboot Frontend**: Multi-stage Docker build (Node.js builds assets, Caddy serves them). Includes automatic HTTPS via Let's Encrypt.
 -   **Kaboot Backend**: Express server for quiz logic and SQLite storage.
--   **Kaboot Frontend**: Static assets served via Caddy.
+-   **Authentik**: Identity Provider for OAuth2/OIDC authentication.
 -   **PostgreSQL**: Database for Authentik.
 -   **Redis**: Cache and task queue for Authentik.
 
@@ -199,11 +196,13 @@ LOG_REQUESTS=true
 
 ### Frontend Configuration
 
-The frontend requires environment variables at **build time** (not runtime):
--   `VITE_API_URL`: `https://kaboot.example.com/api`
--   `VITE_OIDC_AUTHORITY`: `https://auth.example.com/application/o/kaboot/`
+The frontend is built inside Docker using the `KABOOT_DOMAIN` and `AUTH_DOMAIN` variables from your `.env` file. These are passed as build arguments to the Dockerfile:
 
-The `setup-prod.sh` script sets these automatically when building.
+-   `VITE_API_URL`: `https://${KABOOT_DOMAIN}`
+-   `VITE_BACKEND_URL`: `https://${KABOOT_DOMAIN}`
+-   `VITE_AUTHENTIK_URL`: `https://${AUTH_DOMAIN}`
+
+The `setup-prod.sh` script sets these domain variables automatically.
 
 ## Docker Compose Files
 
@@ -260,28 +259,21 @@ auth.example.com {
 }
 ```
 
-**Step 2: Build the Frontend**
-
-```bash
-npm run build
-```
-
-This creates the `dist/` directory with production assets.
-
-**Step 3: Start with Caddy**
+**Step 2: Start with Caddy**
 
 Use both compose files together:
 
 ```bash
-docker compose -f docker-compose.prod.yml -f docker-compose.caddy.yml up -d
+docker compose -f docker-compose.prod.yml -f docker-compose.caddy.yml up -d --build
 ```
 
 This will:
+- Build the frontend inside Docker with production URLs baked in
 - Start all Kaboot services (backend, Authentik, PostgreSQL, Redis)
 - Start Caddy as a reverse proxy on ports 80 and 443
 - Automatically obtain SSL certificates from Let's Encrypt
 
-**Step 4: Verify**
+**Step 3: Verify**
 
 Check that all services are running:
 
@@ -289,10 +281,10 @@ Check that all services are running:
 docker compose -f docker-compose.prod.yml -f docker-compose.caddy.yml ps
 ```
 
-View Caddy logs:
+View frontend/Caddy logs:
 
 ```bash
-docker logs kaboot-caddy
+docker logs kaboot-frontend
 ```
 
 Check Authentik blueprint was applied: