Infrastructure Projet Davai

Ce dépôt contient l'infrastructure as code du projet Davai. Il permet de préparer, sécuriser et administrer un VPS Ubuntu avec Ansible, puis d'y déployer les services de la plateforme.

La configuration couvre notamment :

• les comptes administrateurs et leurs clés SSH ;
• le pare-feu UFW et la protection Fail2ban ;
• Caddy et la gestion automatique des certificats TLS ;
• Docker et Docker Compose ;
• Penpot, Uptime Kuma et Forgejo ;
• un Forgejo Runner pour les pipelines CI/CD ;
• les sauvegardes Restic planifiées avec systemd.

Architecture

Le VPS constitue l'unique hôte de la plateforme. Caddy est installé directement sur le serveur et sert de point d'entrée HTTP et HTTPS. Les applications sont déployées avec Docker Compose et leurs ports web ne sont accessibles que localement, derrière Caddy.

Composant	Rôle
users	Crée les comptes administrateurs et installe leurs clés SSH publiques
firewall	Configure UFW et limite les ports exposés
fail2ban	Protège le service SSH contre les tentatives répétées
caddy	Installe le reverse proxy et configure les domaines
docker	Installe Docker et le plugin Docker Compose
penpot	Déploie la plateforme de conception collaborative
uptime_kuma	Déploie la supervision des services
forgejo	Déploie la forge Git
forgejo_runner	Déploie le runner Forgejo Actions
backup	Configure les sauvegardes Restic automatisées
documentation	Publie le site Starlight de la documentation

Les décisions structurantes sont consignées sous forme d'ADR dans docs/src/content/docs/decisions/adr/.

Organisation du dépôt

.
├── ansible.cfg
├── inventory/
│   ├── bootstrap.yml
│   ├── production.yml
│   └── group_vars/vps/
├── playbooks/
│   ├── bootstrap.yml
│   ├── site.yml
│   ├── check.yml
│   ├── deploy-documentation.yml
│   └── requirements.yml
├── roles/
├── docs/
└── .forgejo/workflows/

• inventory/bootstrap.yml décrit la connexion initiale avec le compte fourni par l'hébergeur.
• inventory/production.yml décrit la connexion courante avec le compte technique ansible.
• playbooks/bootstrap.yml crée les utilisateurs et installe leurs clés SSH.
• playbooks/site.yml applique la configuration et déploie les services.
• docs/ contient le site de documentation Astro/Starlight.

Prérequis

Sur la machine de contrôle :

• Ansible Core ;
• une clé SSH autorisée sur le VPS ;
• Node.js 22 et npm pour construire la documentation ;
• le mot de passe Ansible Vault, conservé hors de Git.

Le serveur cible doit utiliser Ubuntu et être joignable en SSH. Les enregistrements DNS des services doivent pointer vers le VPS avant l'activation de Caddy.

Installer les collections Ansible :

ansible-galaxy collection install --requirements-file playbooks/requirements.yml

Premier déploiement

Le premier déploiement se déroule en deux phases afin de créer le compte technique ansible avant de l'utiliser.

1. Préparer l'accès initial

Adapter inventory/bootstrap.yml avec l'adresse du VPS, le compte initial et la clé SSH fournie à l'hébergeur.

Vérifier la connexion :

ansible vps --inventory inventory/bootstrap.yml --module-name ansible.builtin.ping

Créer les comptes administrateurs et installer leurs clés :

ansible-playbook \
  --inventory inventory/bootstrap.yml \
  playbooks/bootstrap.yml

Important

Garder la session administrateur initiale ouverte jusqu'à avoir vérifié, dans une seconde session, que le compte ansible peut se connecter et utiliser sudo.

2. Déployer l'infrastructure

Adapter inventory/production.yml et les variables de inventory/group_vars/vps/, puis vérifier la connexion :

ansible-playbook playbooks/check.yml

Prévisualiser les changements :

ansible-playbook \
  playbooks/site.yml \
  --check \
  --diff \
  --vault-password-file .vault_pass

Appliquer la configuration :

ansible-playbook \
  playbooks/site.yml \
  --vault-password-file .vault_pass

Les playbooks sont conçus pour être idempotents et peuvent être relancés pour ramener le serveur vers l'état déclaré.

Secrets

Les secrets propres aux services sont stockés dans les fichiers vault_*.yml sous inventory/group_vars/vps/. Ils doivent rester chiffrés avec Ansible Vault.

ansible-vault encrypt inventory/group_vars/vps/vault_<service>.yml
ansible-vault edit inventory/group_vars/vps/vault_<service>.yml

Ne jamais versionner :

• une clé SSH privée ;
• le fichier .vault_pass ;
• un mot de passe ou un jeton en clair ;
• une sauvegarde contenant des données de production.

Documentation

La documentation détaillée se trouve dans docs/src/content/docs/ et couvre les rôles Ansible, les procédures d'exploitation et les décisions d'architecture.

Pour la consulter localement :

cd docs
npm ci
npm run dev

Pour vérifier la génération du site :

cd docs
npm ci
npm run build

La documentation publiée est accessible sur docs.corentin-talour.fr.

Contribuer

Lorsqu'un changement modifie le comportement de l'infrastructure :

1. mettre à jour le rôle ou le playbook concerné ;
2. mettre à jour la page de documentation associée ;
3. ajouter ou modifier un ADR si la décision d'architecture évolue ;
4. vérifier le playbook avec --check --diff ;
5. construire la documentation avec npm run build.

Une modification n'est terminée que lorsque le code, la documentation et les procédures décrivent le même état.