Déploiement MkDocs + Nginx avec Docker¶

Cette procédure décrit comment déployer un site de documentation MkDocs avec le thème Material, servi par Nginx, le tout orchestré avec Docker Compose sur un Raspberry Pi 5.

Informations¶

Prérequis¶

Matériel¶

• Raspberry Pi 5 (ou tout serveur Linux)
• Stockage SSD recommandé

Logiciels¶

• Debian 13 (Trixie) ou équivalent
• Docker et Docker Compose installés

Vérification de Docker¶

docker --version
docker compose version

Si Docker n'est pas installé :

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# Se déconnecter/reconnecter

Architecture¶

graph LR
    A[Client] -->|Port 8080| B[Nginx]
    B -->|Volume partagé| C[Site statique]
    D[MkDocs Build] -->|Génère| C

Étape 1 : Structure du projet¶

Créer le répertoire du projet :

sudo mkdir -p /opt/mkdocs
cd /opt/mkdocs

Structure attendue :

/opt/mkdocs/
├── docker-compose.yml
├── Dockerfile
├── mkdocs.yml
├── requirements.txt
├── docs/
│   ├── index.md
│   └── ...
└── nginx/
    ├── nginx.conf
    └── conf.d/
        └── default.conf

Étape 2 : Fichier Dockerfile¶

FROM squidfunk/mkdocs-material:latest AS builder

WORKDIR /docs

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY mkdocs.yml .
COPY docs/ ./docs/

RUN mkdocs build --strict --verbose

Étape 3 : Fichier docker-compose.yml¶

services:
  mkdocs:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: mkdocs-builder
    volumes:
      - site_data:/output
    entrypoint: ["/bin/sh", "-c"]
    command: ["cp -r /docs/site/* /output/"]
    restart: "no"

  nginx:
    image: nginx:alpine
    container_name: mkdocs-nginx
    depends_on:
      mkdocs:
        condition: service_completed_successfully
    ports:
      - "8080:80"
    volumes:
      - site_data:/usr/share/nginx/html:ro
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
      - ./nginx/conf.d:/etc/nginx/conf.d:ro
    restart: unless-stopped

volumes:
  site_data:

Étape 4 : Configuration Nginx¶

nginx/nginx.conf¶

user nginx;
worker_processes auto;
pid /var/run/nginx.pid;

events {
    worker_connections 1024;
}

http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    sendfile on;
    keepalive_timeout 65;
    gzip on;

    include /etc/nginx/conf.d/*.conf;
}

nginx/conf.d/default.conf¶

server {
    listen 80;
    server_name _;
    root /usr/share/nginx/html;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

Étape 5 : Déploiement¶

Construction et lancement¶

cd /opt/mkdocs
docker compose up -d --build

Vérification¶

docker compose ps

Résultat attendu :

NAME              STATUS
mkdocs-builder    exited (0)
mkdocs-nginx      running (healthy)

Étape 6 : Accès au site¶

Le site est accessible sur :

http://<IP-DU-SERVEUR>:8080

Mise à jour du site¶

Après modification des fichiers Markdown :

docker compose up -d --build mkdocs

Commandes utiles¶

Dépannage¶

docker compose logs mkdocs

docker compose run --rm mkdocs mkdocs build --strict

Retour aux procédures Conteneurisation