fix(security): Remove insecure session secret fallback in compose.debug.yml

TASK-027: The compose.debug.yml file had a publicly known weak session secret as
a fallback value. This has been replaced with an explicit requirement via the :?
bash parameter expansion pattern, forcing developers to set BANGUI_SESSION_SECRET.

Changes:
- Changed BANGUI_SESSION_SECRET fallback to use :? pattern with clear error message
- Created .env.example with placeholder values and generation instructions
- Added first-run setup instructions to Instructions.md
- Verified .env is already in .gitignore

The error message provides clear guidance:
'BANGUI_SESSION_SECRET must be set — generate with: python -c "import secrets; print(secrets.token_hex(32))"'

Severity: Medium
- Prevents exposure of session secret in repositories
- Ensures each environment has unique secrets
- Aligns with production compose.prod.yml which already uses this pattern

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

.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