Documentation Index

Fetch the complete documentation index at: https://snakysec.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

​

Runbook — Setup Mintlify Hobby pour la doc SnakySec

Audience : opérateur MSSP (Nicolas) qui setup le site doc pour la première fois. Durée : 30 min hors propagation DNS (compter 1h total). Pré-requis : compte Mintlify Hobby créé sur dashboard.mintlify.com.

​

Vue d’ensemble

​

Étape A — Créer un GitLab Project Access Token

Important : Mintlify utilise l’endpoint /api/v4/projects/{id}/repository/branches qui requiert le scope read_api. Les Deploy Tokens GitLab ne couvrent PAS read_api (seulement read_repository), donc Mintlify retourne : « An unknown error occurred when attempting to fetch branches. Please check your project ID and private access token. » Solution : utiliser un Project Access Token (PRAT, format glpat-…) au lieu d’un Deploy Token (gldt-…).

1. Aller sur gitlab.com/snakysec-group/mssp-snakysec-multi-tenants
2. Settings → Access Tokens (PAS « Deploy tokens » sous Repository)
3. Cliquer Add new token et remplir :
   • Name : mintlify-read
   • Role : Reporter (lecture seule, suffisant pour Mintlify)
   • Expires at : 1 an depuis aujourd’hui
   • Scopes : cocher read_api ET read_repository
4. Cliquer Create project access token
5. COPIER IMMÉDIATEMENT le token affiché en haut de la page (commence par glpat-). GitLab ne le réaffichera pas.

Mettre un rappel calendrier 30 jours avant expiration pour rotation. Procédure de rotation = recréer un nouveau token + le re-paster dans Mintlify dashboard → Connections.

Si tu avais créé un Deploy Token raté avant : Settings → Repository → Deploy tokens → Revoke. Hygiène = pas de creds inutilisés qui traînent.

​

Étape B — Sauvegarder dans Vault

ROOT_TOKEN=$(docker exec mssp-vault sh -c 'cat /vault/data/init-keys.json' \
              | python -c "import sys,json;print(json.load(sys.stdin)['root_token'])")

docker exec -e VAULT_TOKEN="$ROOT_TOKEN" -e VAULT_SKIP_VERIFY=true mssp-vault \
  vault kv patch mssp/platform \
    mintlify_deploy_token="<COLLER LE TOKEN ICI>" \
    mintlify_deploy_token_username="<COLLER LE USERNAME>" \
    mintlify_deploy_token_expires="2027-05-02"

docker exec -e VAULT_TOKEN="$ROOT_TOKEN" -e VAULT_SKIP_VERIFY=true mssp-vault \
  vault kv get -field=mintlify_deploy_token_expires mssp/platform
# → "2027-05-02"

​

Étape C — Remplir le formulaire « Connect your GitLab repository »

Project ID source : Vault mssp/platform/gitlab_project_id. Pour vérifier :

docker exec -e VAULT_TOKEN="$ROOT_TOKEN" -e VAULT_SKIP_VERIFY=true mssp-vault \
  vault kv get -field=gitlab_project_id mssp/platform

​

Étape D — Push les commits docs

cd "f:/Gitlab/mssp-snakysec-multi-tenants/mssp-snakysec-multi-tenants-main"

# Ajouter les fichiers de config + landing pages
git add docs/docs.json docs/index.mdx docs/quickstart.mdx \
        docs/development.mdx docs/AGENTS.md \
        docs/runbooks/setup-mintlify.md \
        docs/favicon.svg docs/logo/

# Supprimer l'ancien mint.json (schema v3) et le starter Mintlify
git rm docs/mint.json
git rm -r mintlify-community-docs-snakysec-18558c1c-21a4b35509d1e6a77777c391cd7385adfe715932/

git commit -m "feat(docs): setup Mintlify Hobby (docs.json v4 + landing pages)"
git push origin main

​

Étape E — Validation URL temporaire

1. Ouvre l’URL https://<slug>.mintlify.app/ (donnée par Mintlify à l’étape C)
2. Vérifier visuellement :
   • Le logo SnakySec apparaît en haut à gauche (light + dark mode)
   • Les 3 tabs Documentation / Disaster Recovery / Runbooks Ops sont visibles
   • La sidebar charge la liste des 83 pages
   • La search bar fonctionne (taper « écart » doit ramener glossary.md)
   • Une page test : cliquer sur DR Policy dans le tab Disaster Recovery — doit afficher le markdown rendu
3. Onglet Builds sur dashboard.mintlify.com → status success au dernier build

Si build fail : cf. Troubleshooting ci-dessous.

​

Étape F — Custom domain docs.snakysec.com

​

F.1 Côté Mintlify

​

F.2 Côté Cloudflare DNS

1. dash.cloudflare.com → ton domaine snakysec.com → DNS → Records
2. Cliquer Add record :
   • Type : CNAME
   • Name : docs
   • Target : (la valeur fournie par Mintlify)
   • Proxy status : ⚠️ DNS only (gris) — PAS Proxied (orange)
   • TTL : Auto
3. Sauvegarder

Pourquoi DNS only ? Mintlify gère son propre certificat TLS. Si Cloudflare proxy en orange est activé, Cloudflare termine TLS de son côté puis re-établit avec Mintlify → conflit (Mintlify voit une IP Cloudflare au lieu du client final), erreurs 525 SSL handshake failed ou 526 Invalid SSL Certificate.

​

F.3 Propagation DNS

dig docs.snakysec.com CNAME +short
# → doit retourner la cible Mintlify (ex: cname.mintlify.app)

dig docs.snakysec.com A +short
# → doit retourner une IP (résolue par CNAME)

curl -I https://docs.snakysec.com/
# → HTTP/2 200
# → server: Mintlify (ou similaire)

​

Étape G — Validation finale

• ✅ Le site charge sans erreur TLS
• ✅ Logo + favicon SnakySec visibles
• ✅ Search bar fonctionnelle
• ✅ Toutes les 83 pages accessibles via la sidebar (ouvre 5-10 au hasard pour tester)
• ✅ Pas d’erreur 404 sur des liens internes (Mintlify auto-mappe les .md)

Test final recommandé : envoie le lien https://docs.snakysec.com/ à un utilisateur externe (ami, conjoint, prospect non-tech) pour valider que le site charge en HTTPS sans warning, sur mobile et desktop.

​

Troubleshooting

​

Build Mintlify échoue avec « Invalid docs.json »

cd docs
python -c "import json; json.load(open('docs.json'))"
# → si erreur, corriger la syntaxe puis recommiter

​

Build OK mais des pages affichent 404

cd docs
# Liste tous les .md/.mdx référencés dans docs.json
python -c "
import json
d = json.load(open('docs.json'))
paths = []
for tab in d['navigation']['tabs']:
  for grp in tab['groups']:
    paths.extend(grp['pages'])
import os
for p in paths:
  if not (os.path.exists(p + '.md') or os.path.exists(p + '.mdx')):
    print('MISSING:', p)
"

​

Custom domain « Connection refused » ou TLS warning

1. Vérifier dig docs.snakysec.com CNAME +short — la valeur doit être celle donnée par Mintlify, pas un autre target.
2. Vérifier Cloudflare → le record est DNS only (gris), pas proxied (orange).
3. Mintlify dashboard → Custom domain → status doit être « Connected » (pas « Pending »).
4. Si toujours pas OK après 24h : raise issue Mintlify support (mailto:support@mintlify.com).

​

Token Mintlify révoqué ou expiré

1. Recréer un nouveau Deploy Token sur GitLab (étape A)
2. Patcher Vault (étape B)
3. Mintlify dashboard → Connections → mssp-snakysec-multi-tenants → Reauthorize → coller le nouveau token
4. Forcer un rebuild via Mintlify dashboard → Builds → Trigger build

​

Search bar ne trouve rien

• Attendre la fin du build (peut être en cours)
• Vérifier que les pages ont bien un frontmatter title + description (sinon pas indexées par Mintlify)

​

Référence

• docs.json schema Mintlify v4
• GitLab Deploy Tokens
• Cloudflare CNAME setup
• Configuration locale : development.mdx
• Conventions doc : AGENTS.md