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


Difficulté	Intermédiaire
Durée estimée	30 minutes
Dernière mise à jour	Janvier 2025

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

Bash

docker --version
docker compose version

Si Docker n'est pas installé :

Bash

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

Service	Rôle
mkdocs	Construit le site statique à partir des fichiers Markdown
nginx	Sert les fichiers statiques sur le port 8080

Étape 1 : Structure du projet

Créer le répertoire du projet :

Bash

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

Structure attendue :

Text Only

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

Étape 2 : Fichier Dockerfile

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

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

Bash

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

Vérification

Bash

docker compose ps

Résultat attendu :

Text Only

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

Étape 6 : Accès au site

Le site est accessible sur :

Text Only

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

Mise à jour du site

Après modification des fichiers Markdown :

Bash

docker compose up -d --build mkdocs

Commandes utiles

Commande	Description
`docker compose up -d --build mkdocs`	Reconstruire le site
`docker compose logs -f nginx`	Voir les logs Nginx
`docker compose down`	Arrêter les services
`docker compose down -v`	Arrêter et supprimer les volumes

Dépannage

Le site ne s'affiche pas

Vérifier les logs du conteneur mkdocs :

Bash

docker compose logs mkdocs

Erreur de build MkDocs

Vérifier la syntaxe du fichier mkdocs.yml :

Bash

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

Retour aux procédures Conteneurisation