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>
86 lines
3.3 KiB
Docker
86 lines
3.3 KiB
Docker
# ──────────────────────────────────────────────────────────────
|
|
# BanGUI — Backend image (Python / FastAPI)
|
|
#
|
|
# Compatible with Docker and Podman.
|
|
# Build context must be the project root.
|
|
#
|
|
# Usage:
|
|
# docker build -t bangui-backend -f Docker/Dockerfile.backend .
|
|
# podman build -t bangui-backend -f Docker/Dockerfile.backend .
|
|
# ──────────────────────────────────────────────────────────────
|
|
|
|
# ── Stage 1: build dependencies ──────────────────────────────
|
|
FROM docker.io/library/python:3.12-slim AS builder
|
|
|
|
WORKDIR /build
|
|
|
|
# Install build-time system dependencies
|
|
RUN apt-get update \
|
|
&& apt-get install -y --no-install-recommends gcc libffi-dev \
|
|
&& rm -rf /var/lib/apt/lists/*
|
|
|
|
COPY backend/pyproject.toml /build/
|
|
|
|
# Install Python dependencies into a virtual-env so we can copy it cleanly
|
|
RUN python -m venv /opt/venv
|
|
ENV PATH="/opt/venv/bin:$PATH"
|
|
RUN pip install --no-cache-dir --upgrade pip \
|
|
&& pip install --no-cache-dir .
|
|
|
|
# ── Stage 2: runtime image ───────────────────────────────────
|
|
FROM docker.io/library/python:3.12-slim AS runtime
|
|
|
|
LABEL maintainer="BanGUI" \
|
|
description="BanGUI backend — fail2ban web management API"
|
|
|
|
# Non-root user for security
|
|
RUN groupadd --gid 1000 bangui \
|
|
&& useradd --uid 1000 --gid bangui --shell /bin/bash --create-home bangui
|
|
|
|
WORKDIR /app
|
|
|
|
# Copy the pre-built virtual-env
|
|
COPY --from=builder /opt/venv /opt/venv
|
|
ENV PATH="/opt/venv/bin:$PATH" \
|
|
PYTHONDONTWRITEBYTECODE=1 \
|
|
PYTHONUNBUFFERED=1
|
|
|
|
# Copy application source
|
|
COPY backend/app /app/app
|
|
COPY fail2ban-master /app/fail2ban-master
|
|
|
|
# Data directory for the SQLite database
|
|
RUN mkdir -p /data && chown bangui:bangui /data
|
|
VOLUME ["/data"]
|
|
|
|
# Default environment values (override at runtime)
|
|
ENV BANGUI_DATABASE_PATH="/data/bangui.db" \
|
|
BANGUI_FAIL2BAN_SOCKET="/var/run/fail2ban/fail2ban.sock" \
|
|
BANGUI_LOG_LEVEL="info" \
|
|
BANGUI_WORKERS="1"
|
|
|
|
EXPOSE 8000
|
|
|
|
USER bangui
|
|
|
|
# Health-check using the built-in health endpoint
|
|
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
|
|
CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/api/health')" || exit 1
|
|
|
|
# ⚠️ IMPORTANT: Single-Worker Requirement
|
|
# BanGUI must always run as a single worker process:
|
|
# - Do NOT pass --workers or --worker-class to uvicorn
|
|
# - Do NOT use gunicorn with -w 4 or similar
|
|
# - Do NOT override BANGUI_WORKERS to > 1
|
|
#
|
|
# Why? The session cache is process-local. Multiple workers would cause:
|
|
# - Random user logouts (sessions not shared between workers)
|
|
# - Duplicate background jobs (each worker runs the scheduler)
|
|
# - SQLite lock contention and timeouts
|
|
#
|
|
# For high availability, use container orchestration (Kubernetes, Docker Swarm)
|
|
# to run multiple instances, not multiple workers in a single process.
|
|
#
|
|
# See Docs/Architekture.md § Deployment Constraints for details.
|
|
CMD ["uvicorn", "app.main:create_app", "--factory", "--host", "0.0.0.0", "--port", "8000"]
|