ProbatioVault Documentation Site - Setup Guide¶

Documentation centralisée agrégeant les 3 repos GitLab du projet ProbatioVault.

🏗️ Architecture¶

ProbatioVault-infra/docs/       # Repo principal (ce repo)
├── mkdocs.yml                  # Config MkDocs + multirepo
├── docs/                       # Docs infrastructure
│   ├── index.md               # Page d'accueil
│   ├── infrastructure/
│   ├── guides/
│   └── security/
└── .gitlab-ci.yml             # Pipeline build + deploy

ProbatioVault-app/docs/         # Importé via multirepo plugin
└── *.md

ProbatioVault-api/docs/         # Importé via multirepo plugin
└── *.md

Le plugin mkdocs-multirepo-plugin clone automatiquement les repos app et api lors du build et importe leur dossier docs/.

📦 Prérequis¶

1. Clé SSH pour déploiement¶

Générer une paire de clés SSH dédiée pour GitLab CI/CD :

ssh-keygen -t ed25519 -C "gitlab-docs-deploy" -f ~/.ssh/gitlab-docs-deploy

Ajouter la clé publique sur le VPS :

ssh ubuntu@51.68.126.160
sudo -i
cat >> /home/gitlab-docs/.ssh/authorized_keys << 'EOF'
<coller le contenu de ~/.ssh/gitlab-docs-deploy.pub>
EOF

2. Variables GitLab CI/CD¶

Configurer dans GitLab : Settings > CI/CD > Variables

Pour SSH_KNOWN_HOSTS :

ssh-keyscan -H 51.68.126.160 > known_hosts
cat known_hosts  # Copier le contenu dans la variable GitLab

Pour GITLAB_TOKEN : 1. Aller dans GitLab : User Settings > Access Tokens 2. Créer un token avec scope read_repository 3. Copier le token dans la variable GitLab

3. DNS¶

Ajouter l'entrée DNS dans Terraform ou manuellement sur OVH :

# terraform/dns-dev.tf
resource "ovh_domain_zone_record" "docs_dev_cname" {
  zone      = var.domain_name
  subdomain = "docs.dev"
  fieldtype = "CNAME"
  ttl       = 3600
  target    = "${var.domain_name}."
}

Ou manuellement : - Type : CNAME - Sous-domaine : docs.dev - Cible : probatiovault.com.

🚀 Déploiement¶

1. Infrastructure Ansible¶

Déployer le rôle docs sur le VPS Dev :

cd ansible
ansible-playbook playbook.yml \
  -i inventory/dev/hosts.ini \
  --vault-password-file .vault_pass \
  --tags docs

Cela va : - Installer MkDocs + plugins - Créer le user gitlab-docs - Créer /var/www/docs/html/ - Configurer Nginx - Configurer SSL Let's Encrypt

2. GitLab CI/CD¶

Pusher le code sur la branche dev :

cd docs
git add .
git commit -m "feat: setup documentation site"
git push origin dev

Le pipeline GitLab va : 1. Builder le site avec MkDocs (stage build) 2. Déployer sur le VPS Dev via rsync (stage deploy:dev)

3. Vérification¶

Une fois le pipeline terminé, accéder à : - https://docs.dev.probatiovault.com

🛠️ Développement local¶

Installation¶

cd docs
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Créer requirements.txt :

mkdocs-material==9.5.2
mkdocs-multirepo-plugin==0.8.1
mkdocs-git-revision-date-localized-plugin
mkdocs-minify-plugin

Serveur de développement¶

export GITLAB_TOKEN="<votre-token>"
mkdocs serve

Accéder à : http://localhost:8000

Note : Le plugin multirepo va cloner les repos app et api au premier lancement. Cela peut prendre quelques secondes.

Build local¶

mkdocs build --strict

Le site statique est généré dans site/.

📝 Ajouter de la documentation¶

Dans ce repo (infra)¶

Créer simplement un fichier .md dans docs/ :

docs/infrastructure/terraform/new-doc.md

Ajouter dans mkdocs.yml > nav :

nav:
  - Infrastructure:
    - Terraform:
      - New Doc: infrastructure/terraform/new-doc.md

Dans les repos app/api¶

Créer un fichier dans le dossier docs/ du repo concerné :

# Dans ProbatioVault-app
app/docs/architecture/stores.md

# Dans ProbatioVault-api
api/docs/endpoints/auth.md

Le plugin multirepo importe automatiquement tous les fichiers *.md de ces dossiers.

Pour personnaliser la navigation :

# mkdocs.yml
nav:
  - Application Mobile:
    - '!import': app  # Import automatique

Ou avec navigation personnalisée :

nav:
  - Application Mobile:
    - Overview: '!import https://gitlab.com/.../app.git?branch=dev&docs_dir=docs&config=mkdocs.yml'

🔧 Configuration avancée¶

Thème et couleurs¶

Modifier dans mkdocs.yml :

theme:
  palette:
    - scheme: default
      primary: indigo  # Couleur primaire
      accent: indigo   # Couleur accent

Extensions Markdown¶

Extensions déjà activées : - admonition : Boîtes de note/warning/info - pymdownx.superfences : Code fences avec syntaxe - pymdownx.tabbed : Onglets - mermaid : Diagrammes

Exemple :

!!! note "Information"
    Ceci est une note importante.

!!! warning "Attention"
    Ceci est un avertissement.

```mermaid
graph TB
    A --> B

Recherche¶

La recherche est activée par défaut avec le plugin search et le support du français.

Versioning¶

Pour activer le versioning avec mike :

pip install mike
mike deploy --push --update-aliases 1.0 latest
mike set-default --push latest

📊 Monitoring¶

Logs Nginx¶

ssh ubuntu@51.68.126.160
sudo tail -f /var/log/nginx/docs-access.log
sudo tail -f /var/log/nginx/docs-error.log

Pipeline GitLab¶

Surveiller les pipelines dans GitLab : - https://gitlab.com/probatiovault/probatiovault-infra/-/pipelines

Métriques (optionnel)¶

Ajouter un exporter Nginx pour Prometheus :

# Sur le VPS
sudo apt install prometheus-nginx-exporter

🐛 Troubleshooting¶

Le plugin multirepo ne clone pas les repos¶

Vérifier que GITLAB_TOKEN est bien défini :

echo $GITLAB_TOKEN

Vérifier l'URL dans mkdocs.yml :

import_url: 'https://oauth2:${GITLAB_TOKEN}@gitlab.com/probatiovault/app.git?branch=dev'

Erreur SSL lors du déploiement¶

Si Let's Encrypt échoue :

ssh ubuntu@51.68.126.160
sudo certbot --nginx -d docs.dev.probatiovault.com

rsync permission denied¶

Vérifier les permissions :

ssh gitlab-docs@51.68.126.160
ls -la /var/www/docs/

Corriger si nécessaire :

sudo chown -R gitlab-docs:www-data /var/www/docs
sudo chmod -R 755 /var/www/docs

📚 Ressources¶

• MkDocs Material
• MkDocs Multirepo Plugin
• GitLab CI/CD