Lukas
b631c1c546
Graceful shutdown ensures in-flight operations complete before process exits: - Lifespan shutdown handler drains pending tasks with 25s timeout - Scheduler stops accepting new jobs immediately - HTTP session, external logging, scheduler lock, DB conn closed cleanly - 25s Python timeout leaves 5s margin before Docker's 30s SIGKILL Files changed: - backend/app/main.py: enhanced _lifespan shutdown with task drain - Docker/Dockerfile.backend: documented signal handling in header - Docker/docker-compose.yml: added stop_grace_period: 30s - Docker/compose.prod.yml: added stop_grace_period: 30s - Docs/Deployment.md: new Graceful Shutdown section with sequence table - Docs/TROUBLESHOOTING.md: new Graceful Shutdown Issues section Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
98 lines
3.8 KiB
Docker
98 lines
3.8 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 .
|
|
#
|
|
# Signal handling:
|
|
# - STOPSIGNAL defaults to SIGTERM (handled by uvicorn → lifespan shutdown)
|
|
# - stop_grace_period in docker-compose.yml controls Docker's kill timeout
|
|
# - Python code allows 25s for in-flight tasks to drain before hard kill
|
|
# ──────────────────────────────────────────────────────────────
|
|
|
|
# ── 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"
|
|
|
|
# Install curl for healthcheck (used by Docker HEALTHCHECK and Compose healthcheck)
|
|
RUN apt-get update \
|
|
&& apt-get install -y --no-install-recommends curl \
|
|
&& rm -rf /var/lib/apt/lists/*
|
|
|
|
# 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
|
|
# Returns exit 0 (success) for HTTP 200 (fail2ban online)
|
|
# Returns exit 1 (failure) for HTTP 503 (fail2ban offline)
|
|
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
|
|
CMD curl -f 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"]
|