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>
115 lines
3.9 KiB
YAML
115 lines
3.9 KiB
YAML
# ──────────────────────────────────────────────────────────────
|
|
# BanGUI — Production Compose
|
|
#
|
|
# Compatible with:
|
|
# docker compose -f Docker/compose.prod.yml up -d
|
|
# podman compose -f Docker/compose.prod.yml up -d
|
|
# podman-compose -f Docker/compose.prod.yml up -d
|
|
#
|
|
# Prerequisites:
|
|
# Create a .env file at the project root (or pass --env-file):
|
|
# BANGUI_SESSION_SECRET=<random-secret>
|
|
# ──────────────────────────────────────────────────────────────
|
|
|
|
name: bangui
|
|
|
|
services:
|
|
# ── fail2ban ─────────────────────────────────────────────────
|
|
fail2ban:
|
|
image: lscr.io/linuxserver/fail2ban:latest
|
|
container_name: bangui-fail2ban
|
|
restart: unless-stopped
|
|
cap_add:
|
|
- NET_ADMIN
|
|
- NET_RAW
|
|
network_mode: host
|
|
environment:
|
|
TZ: "${BANGUI_TIMEZONE:-UTC}"
|
|
PUID: 0
|
|
PGID: 0
|
|
volumes:
|
|
- fail2ban-config:/config
|
|
- fail2ban-run:/var/run/fail2ban
|
|
- /var/log:/var/log:ro
|
|
healthcheck:
|
|
test: ["CMD", "fail2ban-client", "ping"]
|
|
interval: 30s
|
|
timeout: 5s
|
|
start_period: 15s
|
|
retries: 3
|
|
# NOTE: The fail2ban-config volume must be pre-populated with the following files:
|
|
# • fail2ban/jail.conf (or jail.d/*.conf) with the DEFAULT section containing:
|
|
# banaction = iptables-allports[lockingopt="-w 5"]
|
|
# This prevents xtables lock contention errors when multiple jails start in parallel.
|
|
# See https://fail2ban.readthedocs.io/en/latest/development/environment.html
|
|
|
|
# ── Backend (FastAPI + uvicorn) ─────────────────────────────
|
|
backend:
|
|
build:
|
|
context: ..
|
|
dockerfile: Docker/Dockerfile.backend
|
|
container_name: bangui-backend
|
|
restart: unless-stopped
|
|
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: "info"
|
|
# ⚠️ BANGUI_WORKERS MUST be 1 — see session_cache.py docstring for details
|
|
# BanGUI uses a process-local session cache. Multiple workers in a single process
|
|
# would cause users to be randomly logged out as sessions wouldn't be shared.
|
|
# For HA, run multiple BanGUI instances (each with --workers 1) via orchestration.
|
|
BANGUI_WORKERS: "1"
|
|
BANGUI_SESSION_SECRET: "${BANGUI_SESSION_SECRET:?Set BANGUI_SESSION_SECRET}"
|
|
BANGUI_TIMEZONE: "${BANGUI_TIMEZONE:-UTC}"
|
|
volumes:
|
|
- bangui-data:/data
|
|
- fail2ban-run:/var/run/fail2ban:ro
|
|
- fail2ban-config:/config:rw
|
|
expose:
|
|
- "8000"
|
|
healthcheck:
|
|
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/api/health')"]
|
|
interval: 30s
|
|
timeout: 5s
|
|
start_period: 10s
|
|
retries: 3
|
|
networks:
|
|
- bangui-net
|
|
|
|
# ── Frontend (nginx serving built SPA + API proxy) ──────────
|
|
frontend:
|
|
build:
|
|
context: ..
|
|
dockerfile: Docker/Dockerfile.frontend
|
|
container_name: bangui-frontend
|
|
restart: unless-stopped
|
|
ports:
|
|
- "${BANGUI_PORT:-8080}:80"
|
|
depends_on:
|
|
backend:
|
|
condition: service_healthy
|
|
healthcheck:
|
|
test: ["CMD", "wget", "-qO", "/dev/null", "http://localhost:80/"]
|
|
interval: 30s
|
|
timeout: 5s
|
|
start_period: 5s
|
|
retries: 3
|
|
networks:
|
|
- bangui-net
|
|
|
|
volumes:
|
|
bangui-data:
|
|
driver: local
|
|
fail2ban-config:
|
|
driver: local
|
|
fail2ban-run:
|
|
driver: local
|
|
|
|
networks:
|
|
bangui-net:
|
|
driver: bridge
|