Docs — Site de documentation¶

Le service AKKO Docs sert le site de documentation MkDocs Material en tant que déploiement nginx conteneurisé dans le cluster Kubernetes. Il fournit une documentation bilingue (EN/FR) pour tous les services AKKO, l'architecture, les guides d'administration et les kits de démarrage.

Architecture¶

Navigateur
   |
+--v-----------+
|  Traefik     |
|  (ingress)   |
+--+-----------+
   |
+--v-----------+
|  akko-docs   |
|  (nginx :80) |
|  HTML MkDocs |
+--------------+

L'image akko-docs est construite depuis le répertoire docs/ avec MkDocs Material
Nginx sert le site HTML statique pré-construit
Monte optionnellement un PVC partagé pour les rapports Quarto rendus depuis JupyterHub

URLs¶

Mode	URL
Kubernetes (k3d)	`https://docs.<domaine>`

Configuration (valeurs Helm)¶

akko-docs:
  enabled: true
  image:
    repository: docs
    tag: "2026.03"
  service:
    port: 80
  ingress:
    enabled: true
    host: "docs.akko.local"
  publishedReports:
    enabled: false    # Activer pour servir /reports/ avec du HTML Quarto
    size: 1Gi
  resources:
    requests:
      cpu: 50m
      memory: 32Mi
    limits:
      cpu: 100m
      memory: 64Mi

Healthcheck¶

Nginx répond aux requêtes HTTP sur le port 80 :

livenessProbe:
  httpGet:
    path: /
    port: 80
  initialDelaySeconds: 5
  periodSeconds: 30
readinessProbe:
  httpGet:
    path: /
    port: 80
  initialDelaySeconds: 3
  periodSeconds: 10

RBAC (qui peut accéder)¶

Le site de documentation est accessible publiquement via l'ingress (aucune authentification requise). Il ne contient que de la documentation publique — aucun secret ni information confidentielle.

Construction de l'image¶

L'image docs est construite par helm/scripts/build-images.sh :

docker build -t akko-docs:2026.03 -f docs/Dockerfile docs/

Pour prévisualiser localement avant la construction :

cd docs && mkdocs serve

Fonctionnalités principales¶

Fonctionnalité	Description
Bilingue	Traduction complète EN + FR via le plugin mkdocs-i18n
Thème Material	Mode sombre/clair, recherche, onglets de navigation
Rapports Quarto	PVC partagé optionnel pour les rapports rendus depuis les notebooks
Léger	32 Mi de RAM, HTML statique uniquement

Ressources requises¶

Composant	RAM minimum	Recommandé
Docs (nginx)	32 Mi	64 Mi

Dépannage¶

Le site Docs retourne une 404¶

Symptômes : L'accès à https://docs.<domaine> retourne une 404 ou une page blanche.

Cause : L'image docs n'a pas été reconstruite après les modifications de documentation, ou le tag d'image dans les values ne correspond pas à l'image construite.

Solution :

# Vérifier que le pod tourne
kubectl get pods -n akko -l app.kubernetes.io/name=akko-docs

# Vérifier le tag de l'image
kubectl describe pod -n akko -l app.kubernetes.io/name=akko-docs | grep Image

# Reconstruire et redéployer
bash helm/scripts/build-images.sh
helm upgrade akko helm/akko/ -n akko -f <fichiers-values>

Documentation obsolète après mise à jour¶

Symptômes : Le contenu de la documentation est obsolète malgré des commits récents.

Cause : Le cache de l'image docs n'a pas été invalidé lors de la construction.

Solution :

# Forcer la reconstruction sans cache
docker build --no-cache -t akko-docs:2026.03 -f docs/Dockerfile docs/

# Réimporter dans k3d
k3d image import akko-docs:2026.03 -c akko

# Redémarrer le pod
kubectl rollout restart -n akko deploy/akko-akko-docs