.env.example

@@ -0,0 +1,28 @@
+# ──────────────────────────────────────────────────────────────
+#  BanGUI — Environment Variables Template
+#  Copy this file to .env and fill in the values below
+# ──────────────────────────────────────────────────────────────
+
+# Session Secret (REQUIRED)
+# Generate a secure random secret for session tokens.
+# WARNING: Do not use the same secret across different environments.
+# Generate with: python -c 'import secrets; print(secrets.token_hex(32))'
+# Example value: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
+BANGUI_SESSION_SECRET=
+
+# Timezone (optional, defaults to UTC)
+# Use standard timezone names from the IANA Time Zone Database
+# Examples: America/New_York, Europe/London, Asia/Tokyo, UTC
+BANGUI_TIMEZONE=UTC
+
+# Backend port (optional, defaults to 8000)
+# When using docker-compose, this is the port on your host machine
+BANGUI_BACKEND_PORT=8000
+
+# Frontend port (optional, defaults to 5173)
+# When using docker-compose, this is the port on your host machine
+BANGUI_FRONTEND_PORT=5173
+
+# Public port (optional, defaults to 8080)
+# When using production compose, this is the public-facing port
+BANGUI_PORT=8080

Docker/compose.debug.yml

@@ -60,7 +60,7 @@ services:
       BANGUI_FAIL2BAN_CONFIG_DIR: "/config/fail2ban"
       BANGUI_LOG_LEVEL: "debug"
       BANGUI_ENABLE_DOCS: "true"
-      BANGUI_SESSION_SECRET: "${BANGUI_SESSION_SECRET:-dev-secret-do-not-use-in-production}"
+      BANGUI_SESSION_SECRET: "${BANGUI_SESSION_SECRET:?BANGUI_SESSION_SECRET must be set — generate with: python -c 'import secrets; print(secrets.token_hex(32))'}"
       BANGUI_TIMEZONE: "${BANGUI_TIMEZONE:-UTC}"
       # Secure=false is intentional for local HTTP development.
       # In production, Secure=true prevents session cookies over unencrypted HTTP.

Docs/Instructions.md

@@ -179,7 +179,37 @@ Verify against [Architekture.md](Architekture.md) and the project structure rule
 
 ---
 
-## 7. Dev Quick-Reference
+## 7. First-Run Setup
+
+### Initialize the Development Environment
+
+Before starting the stack for the first time, set up the required environment variables:
+
+1. **Copy the example environment file:**
+   ```bash
+   cp .env.example .env
+   ```
+
+2. **Generate a session secret:**
+   ```bash
+   python -c 'import secrets; print(secrets.token_hex(32))'
+   ```
+   Copy the output and paste it as the value for `BANGUI_SESSION_SECRET` in your `.env` file.
+
+3. **Optional: Customize other settings**
+   - Edit `.env` to adjust timezone, port numbers, or other settings
+   - Default values are sensible for development (UTC, ports 8000/5173)
+
+4. **Start the stack:**
+   ```bash
+   make up
+   ```
+
+**Note:** The session secret is critical for security. Do not commit `.env` to version control — it is already in `.gitignore`. Each environment (dev, staging, production) must have its own unique secret.
+
+---
+
+## 8. Dev Quick-Reference
 
 ### Start / stop the stack