Lukas
c4ede71fa6
Addresses: Backend session cache not cluster-safe (multi-worker issue) Problem: - Session cache is process-local (InMemorySessionCache) - Multi-worker deployments (uvicorn --workers N) create separate processes - Each process has its own independent session cache - Sessions cached in Worker A are invisible to Workers B, C, D - Users randomly logged out when requests land on different workers - Also affects RuntimeState, rate limiter, and background jobs Solution (Option A - Strict single-worker enforcement): - Enhance startup validation with clearer error messages - Update error messages to explain the problem and how to fix it - Document single-worker requirement prominently in Docker configs - Update module docstrings to clarify constraints Changes: 1. app/startup.py: - Enhanced _check_single_worker_mode() error message with troubleshooting - Enhanced _stage_check_worker_mode_and_acquire_lock() error message - Removed unused import 2. app/utils/session_cache.py: - Updated module docstring to explain constraints more clearly - Added references to deployment documentation - Clarified multi-worker solution for future implementation 3. app/utils/runtime_state.py: - Updated module docstring with deployment constraint references - Aligned messaging with session_cache.py 4. Docker/Dockerfile.backend: - Added comprehensive comments about single-worker requirement - Explained impact in multi-worker deployments - Referenced deployment constraints documentation 5. Docker/docker-compose.yml, compose.prod.yml, compose.debug.yml: - Added documentation comments about BANGUI_WORKERS constraint - Explained why single-worker is required 6. backend/tests/test_startup_integration.py: - Fixed test unpacking to match function return signature (3 values, not 2) This ensures multi-worker deployments fail loudly at startup with clear guidance on what went wrong and how to fix it. The database-backed scheduler lock provides defense-in-depth for container orchestration scenarios. For future multi-worker support, implement: - Redis or database-backed session cache - Shared RuntimeState coordination - Distributed APScheduler backend Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
130 lines
4.3 KiB
YAML
130 lines
4.3 KiB
YAML
# ──────────────────────────────────────────────────────────────
|
|
# BanGUI — Debug / Development Compose
|
|
#
|
|
# Compatible with:
|
|
# docker compose -f Docker/compose.debug.yml up
|
|
# podman compose -f Docker/compose.debug.yml up
|
|
# podman-compose -f Docker/compose.debug.yml up
|
|
#
|
|
# Features:
|
|
# - Source code mounted as volumes (hot-reload)
|
|
# - Uvicorn --reload for backend auto-restart
|
|
# - Vite dev server for frontend with HMR
|
|
# - Ports exposed on host for direct access
|
|
# - Debug log level enabled
|
|
# ──────────────────────────────────────────────────────────────
|
|
|
|
name: bangui-dev
|
|
|
|
services:
|
|
# ── fail2ban ─────────────────────────────────────────────────
|
|
fail2ban:
|
|
image: lscr.io/linuxserver/fail2ban:latest
|
|
container_name: bangui-fail2ban-dev
|
|
restart: unless-stopped
|
|
cap_add:
|
|
- NET_ADMIN
|
|
- NET_RAW
|
|
network_mode: host
|
|
environment:
|
|
TZ: "${BANGUI_TIMEZONE:-UTC}"
|
|
PUID: 0
|
|
PGID: 0
|
|
volumes:
|
|
- ./fail2ban-dev-config:/config
|
|
- fail2ban-dev-run:/var/run/fail2ban
|
|
- /var/log:/var/log:ro
|
|
- ./logs:/remotelogs/bangui
|
|
healthcheck:
|
|
test: ["CMD", "fail2ban-client", "ping"]
|
|
interval: 15s
|
|
timeout: 5s
|
|
start_period: 15s
|
|
retries: 3
|
|
|
|
# ── Backend (FastAPI + uvicorn with --reload) ───────────────
|
|
backend:
|
|
build:
|
|
context: ..
|
|
dockerfile: Docker/Dockerfile.backend
|
|
target: runtime
|
|
container_name: bangui-backend-dev
|
|
restart: unless-stopped
|
|
user: "0"
|
|
depends_on:
|
|
fail2ban:
|
|
condition: service_healthy
|
|
environment:
|
|
BANGUI_DATABASE_PATH: "/data/bangui.db"
|
|
BANGUI_FAIL2BAN_SOCKET: "/var/run/fail2ban/fail2ban.sock"
|
|
BANGUI_FAIL2BAN_CONFIG_DIR: "/config/fail2ban"
|
|
BANGUI_LOG_LEVEL: "debug"
|
|
BANGUI_ENABLE_DOCS: "true"
|
|
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.
|
|
BANGUI_SESSION_COOKIE_SECURE: "false"
|
|
# BANGUI_WORKERS should not be set (defaults to 1).
|
|
# Never set it to > 1; the session cache is process-local.
|
|
volumes:
|
|
- ../backend/app:/app/app:z
|
|
- ../fail2ban-master:/app/fail2ban-master:ro,z
|
|
- bangui-dev-data:/data
|
|
- fail2ban-dev-run:/var/run/fail2ban:ro
|
|
- ./fail2ban-dev-config:/config:rw
|
|
ports:
|
|
- "${BANGUI_BACKEND_PORT:-8000}:8000"
|
|
command:
|
|
[
|
|
"uvicorn", "app.main:create_app", "--factory",
|
|
"--host", "0.0.0.0", "--port", "8000",
|
|
"--reload", "--reload-dir", "/app/app"
|
|
]
|
|
healthcheck:
|
|
test: ["CMD-SHELL", "python -c 'import urllib.request; urllib.request.urlopen(\"http://127.0.0.1:8000/api/health\", timeout=4)'"]
|
|
interval: 15s
|
|
timeout: 5s
|
|
start_period: 45s
|
|
retries: 5
|
|
networks:
|
|
- bangui-dev-net
|
|
|
|
# ── Frontend (Vite dev server with HMR) ─────────────────────
|
|
frontend:
|
|
image: node:22-alpine
|
|
container_name: bangui-frontend-dev
|
|
restart: unless-stopped
|
|
working_dir: /app
|
|
environment:
|
|
NODE_ENV: development
|
|
volumes:
|
|
- ../frontend:/app:z
|
|
- frontend-node-modules:/app/node_modules
|
|
ports:
|
|
- "${BANGUI_FRONTEND_PORT:-5173}:5173"
|
|
command: ["sh", "-c", "npm install && npm run dev -- --host 0.0.0.0"]
|
|
depends_on:
|
|
backend:
|
|
condition: service_healthy
|
|
healthcheck:
|
|
test: ["CMD", "wget", "-qO", "/dev/null", "http://localhost:5173/"]
|
|
interval: 15s
|
|
timeout: 5s
|
|
start_period: 30s
|
|
retries: 5
|
|
networks:
|
|
- bangui-dev-net
|
|
|
|
volumes:
|
|
bangui-dev-data:
|
|
driver: local
|
|
frontend-node-modules:
|
|
driver: local
|
|
fail2ban-dev-run:
|
|
driver: local
|
|
|
|
networks:
|
|
bangui-dev-net:
|
|
driver: bridge
|