Zensical¶

Zensical est un générateur de sites statiques Markdown utilisé pour servir la documentation du serveur. Le site est hébergé dans un conteneur Docker dans le LXC 101 (Management).

Configuration¶

• Conteneurs : zensical-builder (build + watcher) + zensical (nginx, serving)
• Image builder : zensical/zensical:latest
• Image web : nginx:alpine
• Port : 8001 → 80 (nginx)
• URL : http://192.168.1.101:8001
• Volumes :
  • /mnt/lxc-data/101-admin/zensical (Proxmox) → /build (builder)
  • /mnt/lxc-data/101-admin/zensical/docs (read-only) → /build/docs (builder)
  • /mnt/lxc-data/101-admin/zensical/site (read-only) → /usr/share/nginx/html (nginx)
• Fichier compose : /mnt/lxc-data/101-admin/docker-compose.yaml
• Mode : build + polling watcher (toutes les 30s) — nginx pour le serving

Pourquoi pas zensical serve ? Le mode serve est un serveur de développement qui consomme 100% CPU en continu. Il est explicitement documenté comme non adapté à la production. On utilise à la place un build statique servi par nginx.

Docker Compose¶

zensical-builder:
    image: zensical/zensical:latest
    container_name: zensical-builder
    volumes:
        - ./zensical:/build
        - ./zensical/docs:/build/docs:ro
    working_dir: /build
    entrypoint: python3
    command: /build/watch.py
    restart: unless-stopped

zensical:
    image: nginx:alpine
    container_name: zensical
    ports:
        - 8001:80
    volumes:
        - ./zensical/site:/usr/share/nginx/html:ro
    depends_on:
        - zensical-builder
    restart: unless-stopped

Watcher (watch.py)¶

Fichier : /mnt/lxc-data/101-admin/zensical/watch.py

Script Python qui : 1. Lance un zensical build au démarrage 2. Vérifie toutes les 30 secondes si des fichiers de /build/docs ont été modifiés depuis le dernier build 3. Si oui, relance un zensical build

Structure¶

/mnt/lxc-data/101-admin/zensical/
├── zensical.toml           # Configuration Zensical
├── watch.py                # Watcher Python (build + polling)
├── docs/                   # Fichiers Markdown (read-only)
│   ├── index.md
│   ├── applications/
│   ├── infrastructure/
│   └── ...
├── site/                   # Site statique généré (servi par nginx)
├── .last_build             # Sentinelle timestamp du dernier build
└── .cache/                 # Cache Zensical

Configuration (zensical.toml)¶

Fichier : /mnt/lxc-data/101-admin/zensical/zensical.toml

Configuration du thème avec features Material Design :

• Navigation instantanée avec barre de progression
• Tracking et path navigation
• Recherche avec suggestions et highlight
• Code copy et annotations
• Dark/light mode automatique

Commandes¶

Gestion du service¶

# Redémarrer les conteneurs
pct exec 101 -- bash -c "cd /opt/docker && docker compose restart zensical-builder zensical"

# Forcer un rebuild immédiat
pct exec 101 -- bash -c "rm -f /opt/docker/zensical/.last_build && docker restart zensical-builder"

# Arrêter/démarrer
pct exec 101 -- bash -c "cd /opt/docker && docker compose stop zensical-builder zensical"
pct exec 101 -- bash -c "cd /opt/docker && docker compose start zensical-builder zensical"

Logs et débogage¶

# Logs du builder (build output)
pct exec 101 -- docker logs -f zensical-builder

# Logs nginx
pct exec 101 -- docker logs -f zensical

# Vérifier le statut
pct exec 101 -- docker ps --filter name=zensical

Inspection¶

# Vérifier que le site a bien été généré
pct exec 101 -- ls -la /opt/docker/zensical/site/

# Vérifier le timestamp du dernier build
pct exec 101 -- cat /opt/docker/zensical/.last_build

# Vérifier le port nginx
curl http://192.168.1.101:8001

Résolution de problèmes¶

Le site ne charge pas¶

# Vérifier les conteneurs
pct exec 101 -- docker ps --filter name=zensical
pct exec 101 -- docker logs --tail 30 zensical
pct exec 101 -- docker logs --tail 30 zensical-builder

# Vérifier le port
pct exec 101 -- ss -tuln | grep 8001
curl http://192.168.1.101:8001

Erreurs de build¶

# Vérifier les logs du builder pour erreurs
pct exec 101 -- docker logs zensical-builder

# Vérifier le montage du volume docs
pct exec 101 -- ls -la /opt/docker/zensical/docs/

Maintenance¶

Mise à jour des images¶

pct exec 101 -- bash -c "cd /opt/docker && docker compose pull zensical-builder zensical"
pct exec 101 -- bash -c "cd /opt/docker && docker compose up -d zensical-builder zensical"

Sauvegarde¶

Les fichiers sources sont sauvegardés via le système de backup Proxmox (LXC).

Le site généré (site/) peut être régénéré depuis les sources à tout moment.