Guidelines

Principes et conventions de cette documentation.

Ces guidelines s'appliquent à toute contribution, qu'elle soit faite par des humains ou des agents IA, et doivent être suivies rigoureusement pour assurer la cohérence et la qualité du contenu.

Principes Fondamentaux

1. État Réel vs Process

✅ Documenter l'état actuel du serveur

Configuration réelle en production
Chemins et commandes actuels
Valeurs et paramètres effectifs

❌ Ne pas documenter

Cheminement d'implémentation historique
États intermédiaires ou temporaires
Process de décision sauf si critique pour le futur
Statuts datés ("en cours le 28/01/2026")

Exemple :

✅ BON

## Backup PBS

- Datastore: `/mnt/datastore` (100GB)
- Rétention: keep-daily=7, keep-weekly=4, keep-monthly=3
- Scripts: `/usr/local/bin/backup-*.sh`

❌ MAUVAIS

## Backup PBS - Déploiement

Le 28 janvier nous avons déployé le backup...
Étape 1: créer le script...
Étape 2: tester...
État: En cours de finalisation

2. Pas de Redondance

Un fait = un endroit dans la documentation
Utiliser des liens entre pages plutôt que dupliquer
Pages index pour vue d'ensemble, détails dans sous-pages
Corriger ou augmenter le contenu existant plutôt que créer de nouvelles pages

Exemple :

✅ BON
Voir configuration [MergerFS](../storage/mergerfs.md) pour détails.

❌ MAUVAIS
MergerFS est configuré avec les options suivantes:

- cache.files=partial
- dropcacheonclose=true
  [...]
  (copier-coller depuis storage/mergerfs.md)

3. Référencer le Serveur, Pas Dupliquer

❌ Ne pas inclure le contenu des scripts/configs

Les scripts sont versionnés sur le serveur
Risque de désynchronisation

✅ Référencer par path et décrire

## Script Backup Host

**Path:** `/usr/local/bin/backup-proxmox-host.sh`

**Fonction:** Sauvegarde configs host Proxmox vers Google Drive

**Contenu sauvegardé:**

- `/etc/pve/` - Configs Proxmox
- `/etc/network/` - Réseau
- `/etc/fstab` - Montages

**Exécution:** Cron daily 05:00

4. Outils VS Code

Pour toute lecture ou modification de documentation :

✅ Utiliser les outils VS Code

edit (en mode agent) : createDirectory, createFile, editFiles...
read : read_file, text_search, problems, terminalLastCommand...
search : changes, codebase, file_search, list_directory, searchResults, textSearch, usages...
et tout autre outil disponible

Permet à l'utilisateur de suivre l'avancement, visualiser les modifications via diff et revert si nécessaire.

Si les outils sont indisponible, l'indiquer à l'utilisateur plutôt que de copier-coller du contenu ou lui indiquer la marche à suivre.

❌ Ne pas utiliser

cat > pour créer des fichiers complets
echo pour append du contenu
Édition manuelle via terminal

4. Informations du serveur, pas encyclopédie

Ne pas inclure des informations générales qui ne sont pas spécifiques au serveur documenté.

Tabler sur la capacité de l'utilisateur à rechercher des informations générales en ligne ou via des commandes shell.

Si nécessaire, lier vers des ressources externes ou des documentations officielles.

Structure Pages

Longueur

Idéal : 150 lignes
Maximum : 300 lignes
Si >300L : Fragmenter en sous-pages

Titres

Maximum : 4-5 niveaux de titres par page
Structure typique :
- # Titre page (1 seul)
- ## Sections principales (3-4)
- ### Sous-sections (si nécessaire)
- #### Détails (rare)

Organisation

Préférer :

Pages courtes et nombreuses
Liens entre pages
Pages index pour navigation

Éviter :

Pages monolithiques >500L
Tout-en-un sans structure

Exemple structure :

backup/
├── index.md           # Vue d'ensemble 150L
├── pbs.md             # Proxmox Backup Server 200L
├── scripts.md         # Scripts backup 150L
├── offsite.md         # Google Drive 180L
└── monitoring.md      # Vérification 120L

Pages Index

Chaque dossier doit avoir un index.md :

Vue d'ensemble du dossier
Liste des sous-pages avec descriptions
Liens vers contenu détaillé

mkdocs.yml

nav:
    - Section:
          - section/index.md # Overview toujours en premier
          - section/page2.md
          - Page 1: section/page1.md # Si le titre de la page est trop long et pertinent à conserver

Pages Annexes

Pages contextuelles ou historiques peuvent être omises de la nav :

Guides de migration complétés
Analyses techniques détaillées
Historique de décisions

Elles restent accessibles via liens internes.

Contenu

Commandes

Toujours fournir commandes testées et fonctionnelles :

## Vérifier Backups PBS

\`\`\`bash

# État backups récents

pct exec 102 -- proxmox-backup-manager task list --limit 10

# Espace datastore

df -h /mnt/pve/pbs-datastore/datastore/
\`\`\`

Configurations

Référencer fichiers de config avec leur path :

## Configuration MergerFS

**Fichier:** `/etc/fstab`

**Options actives:**

- `cache.files=partial`
- `dropcacheonclose=true`
- `category.create=mfs`

Voir [mergerfs](mergerfs.md) pour détails options.

Éviter Info Obsolète

❌ Éviter mentions qui deviennent rapidement fausses :

"Actuellement nous utilisons..." → utiliser présent affirmé
"Version 3.4.8-2" si change souvent → "Version installée: proxmox-backup-manager --version"
Dates spécifiques de déploiement
"En cours de..." ou "bientôt"

Liens vers des pages

Utiliser des liens relatifs
Utiliser des titres explicites (pas "page.md")

Exemples

✅ Bonne Page (150L)

# Proxmox Backup Server

PBS installé dans LXC 102 pour backups automatiques LXC.

## Configuration

- **Datastore:** `/mnt/datastore` (100GB rootfs)
- **Rétention:** keep-daily=7, keep-weekly=4, keep-monthly=3
- **Config:** `/etc/pve/storage.cfg`

## Backups Automatiques

LXC sauvegardés quotidiennement à 03:00 :

- LXC 100 (docker-media)
- LXC 101 (docker-management)

Format : chunks PBS avec déduplication.

## Vérification

\`\`\`bash

# Derniers backups

pct exec 102 -- proxmox-backup-manager task list --limit 10

# Espace utilisé

df -h /mnt/pve/pbs-datastore/datastore/
\`\`\`

## Restauration

Voir [Restoration](../recovery/restoration.md).

## Monitoring

Voir [Monitoring](monitoring.md).

❌ Mauvaise Page (500L monolithique)

# Backup Infrastructure Complete Guide

[200 lignes d'historique de déploiement]
[150 lignes de scripts copiés-collés]
[100 lignes de troubleshooting]
[50 lignes de monitoring]

Maintenance Documentation

Mise à Jour

Lors de changements serveur :

Identifier pages impactées (grep_search)
Mettre à jour configs/commandes
Vérifier liens internes
Tester commandes documentées

Review Régulier

Trimestriel : vérifier obsolescence
À chaque update majeure : review section concernée
Supprimer info obsolète plutôt qu'ajouter versions