Documentation

Le rôle documentation déploie sur le VPS le site statique généré par Astro Starlight et configure Caddy pour le rendre accessible en HTTPS.

Il est responsable de :

• vérifier que le build Starlight existe ;
• créer le répertoire de publication sur le VPS ;
• synchroniser les fichiers du site ;
• appliquer les propriétaires et permissions attendus ;
• supprimer les anciennes configurations Caddy ;
• déployer la configuration Caddy du site ;
• valider et recharger Caddy ;
• vérifier que le site répond correctement en HTTPS.

Note

Le rôle ne construit pas la documentation. C’est le pipeline CI/CD qui réalise le build de la documentation.

Fonctionnement

La documentation est construite depuis le dossier docs via la commande npm run build qui génère le site statique.

Astro génère alors le site statique dans le dossier suivant :

docs/dist/

La synchronisation utilise l’option delete. Les fichiers qui n’existent plus dans le build local sont donc également supprimés du VPS.

Le rôle applique ensuite l’utilisateur et le groupe caddy à l’ensemble des fichiers déployés.

Enfin, une configuration Caddy est ajoutée afin de publier directement les fichiers statiques avec la directive file_server.

Structure du rôle

roles/documentation/
├── defaults/
│   └── main.yml                # Variables du rôle
├── handlers/
│   └── main.yml                # Rechargement de Caddy si nécessaire
├── tasks/
│   └── main.yml                # Tâches de déploiement
└── templates/
    └── documentation.conf.j2   # Virtual host de la documentation

Architecture

Client
    │
    ▼
Caddy
    │ file_server
    ▼
/var/www/documentation

Variables

Les variables sont contenues dans le fichier main.yml dans le dossier defaults.

Variables globales

Variable	Type	Description
documentation_domain	chaîne de caractères	Nom de domaine public de la documentation
documentation_build_directory	chaîne de caractères	Chemin local vers le build Starlight
documentation_web_root	chaîne de caractères	Répertoire de publication sur le VPS
documentation_caddy_config	chaîne de caractères	Destination de la configuration Caddy
documentation_legacy_caddy_configs	liste de chaînes	Anciennes configurations Caddy à supprimer

Exemple de fichier de configuration

documentation_domain: docs.corentin-talour.fr

documentation_build_directory: "{{ playbook_dir }}/../docs/dist"
documentation_web_root: /var/www/documentation
documentation_caddy_config: /etc/caddy/sites/documentation.conf
documentation_legacy_caddy_configs:
  - /etc/caddy/sites/docs.conf

Configuration Caddy

Le template documentation.conf.j2 génère une configuration semblable à celle-ci :

docs.corentin-talour.fr {
    root * /var/www/documentation

    file_server
}

La directive root indique le répertoire contenant le site.

La directive file_server demande à Caddy de servir directement les fichiers statiques.

Caddy gère automatiquement le certificat TLS du domaine, à condition que le DNS soit correctement configuré et que le VPS soit accessible depuis Internet.

Déploiement

Le rôle réalise les opérations suivantes :

1. Il vérifie sur la machine exécutant Ansible que le fichier dist/index.html existe.
2. Il interrompt le playbook si le build Starlight est absent.
3. Il crée le répertoire /var/www/documentation.
4. Il définit caddy comme utilisateur et groupe propriétaires du répertoire.
5. Il synchronise le contenu du build dans le répertoire web avec rsync.
6. Il supprime du VPS les fichiers qui ne sont plus présents dans le build.
7. Il applique récursivement l’utilisateur et le groupe caddy aux fichiers déployés.
8. Il supprime les anciennes configurations listées dans documentation_legacy_caddy_configs.
9. Il génère /etc/caddy/sites/documentation.conf depuis le template.
10. Il valide la configuration complète de Caddy.
11. Il exécute immédiatement les handlers en attente.
12. Il recharge Caddy lorsqu’un changement le nécessite.
13. Il vérifie que le site répond avec un statut HTTP 200.

Synchronisation des fichiers

La synchronisation est réalisée avec le module ansible.posix.synchronize.

Il s’appuie sur rsync pour copier le contenu du build vers le VPS :

- name: Synchronize Starlight build
  ansible.posix.synchronize:
    src: "{{ documentation_build_directory }}/"
    dest: "{{ documentation_web_root }}/"
    archive: true
    delete: true
    owner: false
    group: false
    rsync_opts:
      - "--chmod=Du=rwx,Dgo=rx,Fu=rw,Fgo=r"

Les permissions appliquées sont les suivantes :

• le propriétaire peut lire, écrire et traverser les répertoires ;
• le groupe et les autres utilisateurs peuvent lire et traverser les répertoires ;
• le propriétaire peut lire et modifier les fichiers ;
• le groupe et les autres utilisateurs peuvent lire les fichiers.

L’option delete: true garantit que le contenu du VPS correspond exactement au build local.

Gestion des anciennes configurations

Le rôle supprime les fichiers contenus dans la variable documentation_legacy_caddy_configs.

Par défaut, le fichier suivant est supprimé :

/etc/caddy/sites/docs.conf

Cette étape permet d’éviter que deux configurations Caddy différentes utilisent le même nom de domaine.

Pour supprimer plusieurs anciennes configurations :

documentation_legacy_caddy_configs:
  - /etc/caddy/sites/docs.conf
  - /etc/caddy/sites/old-documentation.conf

Si aucune ancienne configuration ne doit être supprimée :

documentation_legacy_caddy_configs: []

Handler

Le rôle contient un handler chargé de recharger Caddy :

- name: Reload Caddy
  ansible.builtin.systemd:
    name: caddy
    state: reloaded

Il est déclenché lorsqu’une des opérations suivantes modifie le VPS :

• la synchronisation du site ;
• la suppression d’une ancienne configuration ;
• la modification de la configuration Caddy.

La tâche flush_handlers applique les changements avant la vérification HTTP finale.

Le service Caddy est rechargé et non redémarré. Cela permet d’appliquer la nouvelle configuration sans arrêter complètement le service.

Déploiement automatique

Le workflow Forgejo construit et déploie automatiquement la documentation lors d’une modification de l’un des éléments suivants :

• le dossier docs/ ;
• le rôle roles/documentation/ ;
• le playbook playbooks/deploy-documentation.yml ;
• le fichier playbooks/requirements.yml ;
• l’inventaire ;
• le workflow de déploiement.

Le pipeline réalise les opérations suivantes :

1. récupération du dépôt ;
2. installation des dépendances système ;
3. installation des dépendances Starlight avec npm ci ;
4. construction du site avec npm run build ;
5. vérification de la présence de docs/dist/index.html ;
6. installation d’Ansible ;
7. installation des collections Ansible ;
8. configuration de la clé SSH ;
9. ajout du VPS aux hôtes SSH connus ;
10. configuration du mot de passe Ansible Vault ;
11. test de la connexion Ansible ;
12. exécution du playbook ;
13. vérification finale du site avec curl.

Le workflow peut également être lancé manuellement grâce à workflow_dispatch.

Vérification manuelle

Vérifier que le site répond

curl -I https://docs.corentin-talour.fr/

Résultat attendu :

HTTP/2 200

Valider la configuration Caddy

caddy validate \
  --config /etc/caddy/Caddyfile \
  --adapter caddyfile

Vérifier l’état du service Caddy :

systemctl status caddy

Vérifier les fichiers déployés

ls -la /var/www/documentation

Vérifier la présence de la page d’accueil

test -f /var/www/documentation/index.html

Vérifier la configuration du site

cat /etc/caddy/sites/documentation.conf