diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..fd65dac
--- /dev/null
+++ b/.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
diff --git a/Docker/compose.debug.yml b/Docker/compose.debug.yml
index 7f32f5c..9186d05 100644
--- a/Docker/compose.debug.yml
+++ b/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.
diff --git a/Docs/Instructions.md b/Docs/Instructions.md
index 76b0745..05b28b2 100644
--- a/Docs/Instructions.md
+++ b/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