# Git and local dev files .git .github # Node / frontend artifacts node_modules dist build # Python cache __pycache__/ *.pyc *.pyo *.pyd # Misc .env *.log *.tar.gz *.zip .dockerignore Dockerfile README.md
FROM python:3.12.13-bookworm
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
WORKDIR /app
# Install system dependencies for MkDocs and Git-based plugins
RUN apt-get update && apt-get install -y --no-install-recommends \
git \
ca-certificates && rm -rf /var/lib/apt/lists/*
# Ensure latest pip
RUN python -m pip install --upgrade pip
# Copy source code first so we can build docs from it
COPY . /app
# Install MkDocs and plugins (including Git-based markdown-include)
RUN pip install --no-cache-dir \
mkdocs-material mkdocs-video mkdocs-redirects mkdocs-glightbox mkdocs-rss-plugin \
git+https://github.com/pikvm/markdown-include
# Build the MkDocs site from the repository
RUN mkdocs build --clean
EXPOSE 8000
# Serve the site in foreground for runtime
CMD ["bash","-lc","mkdocs serve -a 0.0.0.0:8000"]
Concerns: MkDocs build runs at image build time and pulls plugins from GitHub; if network access is blocked, the build could fail., The build assumes a MkDocs configuration (mkdocs.yml) and docs/ structure in the repo; missing structure will cause a build failure., The CMD uses bash -lc; ensure bash is present in the base image (some minimal images may not include bash). Smoke [FAIL]: python -c 'import mkdocs, sys; print(mkdocs.__version__) Output: sh: 1: Syntax error: Unterminated quoted string Smoke [PASS]: test -f /app/site/index.html && echo site_built || echo site_missing
# Multi-stage build: build MkDocs site then serve as static files
FROM python:3.12.13-bookworm AS builder
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
WORKDIR /src
# Install build dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
git \
ca-certificates && rm -rf /var/lib/apt/lists/*
# Copy source code
COPY . /src
# Upgrade pip and install MkDocs and plugins
RUN python -m pip install --upgrade pip
RUN pip install --no-cache-dir \
mkdocs-material mkdocs-video mkdocs-redirects mkdocs-glightbox mkdocs-rss-plugin \
git+https://github.com/pikvm/markdown-include
# Build the MkDocs site
RUN mkdocs build --clean
# Runtime stage: serve the static site with Python's simple HTTP server
FROM python:3.12.13-bookworm AS runtime
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
WORKDIR /app
# Copy the generated site from builder
COPY --from=builder /src/site /app/site
# Expose port for the static site
EXPOSE 8000
# Serve the site
CMD ["python","-m","http.server","8000","--directory","/app/site"]
Smoke [PASS]: test -f /app/site/index.html Smoke [PASS]: test -s /app/site/index.html Smoke [PASS]: ls -la /app/site