Aller au contenu

Héberger le portail de doc (Dokploy)

Servir le site statique MkDocs Material derrière Traefik, sur le VPS Dokploy auto-hébergé — même stack que app.entretien-sources.nedcore.net. Aucune donnée confidentielle : image autosuffisante, aucun volume.

Aperçu local

uv pip install --python .venv-linux/bin/python "mkdocs-material>=9.5,<10"
mkdocs serve            # rechargement à chaud sur http://127.0.0.1:8000
mkdocs build            # rend le site statique dans site/

La config est mkdocs.yml (racine du dépôt) ; le contenu, docs/.

Artefacts

Sous docs/deploy/ :

  • Dockerfile — multi-stage : mkdocs build (thème Material) puis service nginx:alpine sur le port 80.
  • nginx.conf — try_files $uri $uri/ (URLs « répertoire » de Material) + page 404.html stylée.
  • docker-compose.yml — service docs, expose: 80, dokploy-network externe, restart: unless-stopped.

Déployer

  1. Dans Dokploy, créer une application Compose pointant sur le dépôt bfev.
  2. Compose Path : docs/deploy/docker-compose.yml (le build context ../.. = racine du dépôt est déjà fixé dans le compose).
  3. Onglet Domains : ajouter <sous-domaine>.nedcore.net (en service : docs-bfev-ghg.nedcore.net) → service docs, port 80, HTTPS letsencrypt.
  4. Deploy. Le build exécute mkdocs build, nginx sert /usr/share/nginx/html.

Pièges (VPS partagé)

  • dokploy-network externe : le service doit y être attaché (déjà dans le compose) sinon Traefik ne le voit pas → 502.
  • expose et non ports : pas de publication d'hôte, le VPS partage le 80/443 avec d'autres apps ; Traefik route en interne. Publier ports: provoquerait un conflit (Apache/autres).
  • DNS Traefik périmé après redeploy : si 502 juste après un redéploiement, l'IP du conteneur a changé et Traefik garde l'ancienne quelques instants — re-déclencher le deploy ou attendre le rafraîchissement.
  • Rebuild obligatoire après changement de doc : pas de volume monté — toute modif docs/** impose un nouveau build d'image (Deploy), pas un simple restart.

Versions en ligne

MkDocs Material gère le multi-versions avec son outil natif mike (déploie chaque version dans un sous-dossier et écrit un sélecteur). À brancher si le besoin de versionner le portail public apparaît ; le build d'image servira alors l'arbre produit par mike au lieu du site/ simple.