Dashboard Homer & MkDocs¶

Architecture¶

Le serveur IA expose deux interfaces web :

Homer Dashboard¶

Présentation¶

Homer est un dashboard statique simple et élégant qui centralise l'accès à tous les services du serveur IA.

Fonctionnalités : - 🎨 Thème clair/sombre automatique - 📱 Responsive (mobile-friendly) - ⚡ Statique (aucun backend) - 🔧 Configuration YAML simple

Configuration¶

Le fichier de configuration se trouve dans /data/homer/config.yml.

Structure :

title: "ProbatioVault IA Server"
subtitle: "Infrastructure & Services Dashboard"

services:
  - name: "Catégorie"
    icon: "fas fa-icon"
    items:
      - name: "Service"
        logo: "assets/tools/logo.png"
        subtitle: "Description"
        url: "http://192.168.1.82:port"
        tag: "tag"

Ajouter un service¶

1. Éditer le fichier de configuration :

ssh ProbatioVault-IA-Server
sudo vim /data/homer/config.yml

1. Ajouter un service dans une catégorie existante :

- name: "Nom du service"
  icon: "fas fa-icon"  # FontAwesome 5
  subtitle: "Description courte"
  url: "http://192.168.1.82:8888"
  tag: "category"

1. Redémarrer Nginx :

sudo systemctl restart nginx

Personnalisation¶

Logo : - Placer votre logo dans /data/homer/assets/logo.png - Référencer dans config.yml : logo: "logo.png"

Icônes de services : - Placer dans /data/homer/assets/tools/service.png - Référencer dans config.yml : logo: "assets/tools/service.png"

Thème : - Modifier les couleurs dans la section colors du config.yml

MkDocs Documentation¶

Présentation¶

MkDocs génère automatiquement une documentation navigable à partir des fichiers Markdown du projet.

Fonctionnalités : - 📖 Génération automatique depuis les *.md - 🔍 Recherche full-text - 📅 Date de dernière modification (Git) - 🎨 Thème Material Design - 🌓 Mode clair/sombre

Structure¶

/opt/probatiovault-ia-server/
├── mkdocs.yml           # Configuration MkDocs
├── docs-site/           # Sources Markdown
│   ├── index.md         # Page d'accueil (README.md)
│   ├── plex-setup.md
│   ├── dashboard-setup.md
│   └── ...
└── /var/www/mkdocs/     # Site généré (HTML)

Ajouter une page¶

Option 1 - Créer directement dans docs/ :

cd /opt/probatiovault-ia-server
vim docs/nouveau-guide.md

Option 2 - Via GitLab (recommandé IaC) :

1. Créer le fichier en local : docs/nouveau-guide.md
2. Commit et push
3. Le pipeline GitLab redéploiera automatiquement

Rebuild manuel :

ssh ProbatioVault-IA-Server
cd /opt/probatiovault-ia-server
sudo systemctl restart mkdocs

Le serveur MkDocs en mode dev reload automatiquement les changements.

Navigation¶

La navigation est auto-générée via le plugin awesome-pages.

Organisation automatique : - index.md → Page d'accueil - docs/*.md → Pages dans l'ordre alphabétique - Dossiers → Sections

Organisation manuelle (optionnel) :

Créer un fichier .pages dans docs-site/ :

nav:
  - Home: index.md
  - Installation:
    - Ollama: ollama-setup.md
    - Plex: plex-setup.md
    - Dashboard: dashboard-setup.md
  - Configuration: ...

Syntaxe Markdown étendue¶

MkDocs supporte les extensions PyMdown :

Admonitions (encadrés) :

!!! warning "Attention"
    Ceci est un avertissement

!!! note "Note"
    Ceci est une note

!!! tip "Astuce"
    Ceci est une astuce

Code avec coloration :

```python
def hello():
    print("Hello World")

**Onglets** :

```markdown
=== "Python"
    ```python
    print("Hello")
    ```

=== "JavaScript"
    ```javascript
    console.log("Hello");
    ```

Déploiement¶

Via GitLab CI/CD (recommandé)¶

Les playbooks sont dans le dépôt :

1. Commit et push :

git add ansible/playbooks/install-homer.yml ansible/playbooks/install-mkdocs.yml
git commit -m "feat: add Homer dashboard and MkDocs documentation"
git push origin main

1. Approuver les jobs dans GitLab :
2. ansible:homer
3. ansible:mkdocs

Déploiement local (test)¶

cd /opt/probatiovault-ia-server

# Homer
ansible-playbook ansible/playbooks/install-homer.yml -i ansible/inventory/hosts

# MkDocs
ansible-playbook ansible/playbooks/install-mkdocs.yml -i ansible/inventory/hosts

Vérification¶

Homer¶

# Vérifier Nginx
systemctl status nginx

# Tester l'accès
curl http://localhost:8080

Ouvrir dans un navigateur : http://192.168.1.82:8080

MkDocs¶

# Vérifier le service
systemctl status mkdocs

# Tester l'accès
curl http://localhost:8000

Ouvrir dans un navigateur : http://192.168.1.82:8000

Troubleshooting¶

Homer ne s'affiche pas¶

# Vérifier les logs Nginx
sudo journalctl -u nginx -f

# Vérifier les permissions
ls -la /data/homer/

# Tester la config Nginx
sudo nginx -t

MkDocs ne démarre pas¶

# Vérifier les logs
sudo journalctl -u mkdocs -f

# Vérifier la config
cd /opt/probatiovault-ia-server
mkdocs build --config-file mkdocs.yml --verbose

# Vérifier les dépendances Python
pip3 list | grep mkdocs

Pages manquantes dans MkDocs¶

# Vérifier les fichiers sources
ls -la /opt/probatiovault-ia-server/docs-site/

# Reconstruire le site
cd /opt/probatiovault-ia-server
sudo mkdocs build --config-file mkdocs.yml --site-dir /var/www/mkdocs --clean

# Redémarrer le service
sudo systemctl restart mkdocs

Accès externe (optionnel)¶

Pour accéder depuis Internet (via reverse proxy Nginx) :

Homer :

location /dashboard {
    proxy_pass http://192.168.1.82:8080;
    proxy_set_header Host $host;
}

MkDocs :

location /docs {
    proxy_pass http://192.168.1.82:8000;
    proxy_set_header Host $host;
}

Avantages¶

✅ Homer : Point d'entrée unique pour tous les services ✅ MkDocs : Documentation vivante et synchronisée avec le code ✅ IaC : Reproductible, versionné, automatisé ✅ Léger : Aucune base de données, statique ✅ Recherche : MkDocs indexe tout le contenu Markdown