Documentation

Pré-requis

Avant de commencer, assurez-vous de disposer des éléments suivants :

VPS/Serveur

Versant s'installe sur votre propre serveur. Vous devez souscrire à une offre serveur ou VPS chez un hébergeur. Un simple VPS suffira amplement, mais c'est vous qui décidez ce qui vous convient le mieux.

Nom de domaine

Vous aurez besoin d'un nom de domaine (ex: crashout.fr) et d'un accès à sa configuration DNS pour le pointer vers votre VPS/serveur.

Port 25 (SMTP) ouvert

Pour pouvoir pleinement utiliser le serveur mail, le port 25 doit être ouvert sur votre VPS. Certains hébergeurs le bloquent par défaut, d'autres l'ouvrent sur demande. Renseignez-vous avant de souscrire.

L'atout de Versant est de vous permettre de disposer facilement de votre propre serveur mail, avec vos propres adresses mail liées à votre site.

Alternative SMTP externe :vous pouvez aussi configurer un service SMTP tiers (Brevo, Mailjet, etc.) depuis le panel admin (Paramètres → Mail), même si le port 25 est bloqué.

Prérequis techniques

Tutoriel d'installation

Voici un guide pas à pas pour installer votre première instance Versant, de l'achat du VPS/Serveur jusqu'à l'onboarding. Suivez les 10 étapes ci-dessous.

1. Achetez un domaine

Une fois que vous avez trouvé un nom de domaine cool pour votre site, rendez-vous chez un registraire fiable pour l'acheter. Vous pouvez généralement acheter le domaine auprès du même hébergeur chez qui vous allez prendre votre VPS. Cout estimé : entre 2 et 15 euros par an.

2. Achetez un VPS/Serveur

Choisissez un hébergeur (de préférence européen, ou encore mieux, français lol). Un VPS à 1 CPU / 1 GB RAM suffit pour commencer. Après l'achat, vous recevrez normalement un e-mail avec l'adresse IP et le mot de passe root de votre VPS/serveur. Coût estimé : à partir de 5 euros par mois.

3. Obtenez l'IP du VPS/Serveur

L'IP de votre VPS/Serveur vous sera généralement communiquée dans l'e-mail d'activation. Sinon, vous la retrouverez sur le tableau de bord de votre hébergeur. Notez-la, vous en aurez besoin pour la connexion SSH et les DNS.

4. Pointez votre domaine vers le VPS/Serveur

Allez dans le tableau de bord de votre registraire et créez deux enregistrements DNS de type A :

La propagation DNS prend de quelques secondes à quelques minutes. Pour vérifier la propagation, ouvrez un terminal sur votre ordinateur et tapez :

dig crashout.fr

Si la propagation est active, la réponse devrait contenir l'adresse IP de votre VPS.

De toutes façons, durant l'installation, le script vérifiera lui-même si tout est en place. Si votre repointage DNS est bien paramétré, l'installation affichera :

5. Connectez-vous au VPS/Serveur

Connectez-vous au VPS/serveur. Depuis votre machine locale, tapez :

ssh root@<IP_de_votre_VPS>

Puis entrez votre mot de passe.

6. Installez Docker et Git

Une fois connecté au VPS, installez Docker et Git :

curl -fsSL https://get.docker.com | sh
apt install -y git

7. Lancez le script d'installation

Téléchargez et exécutez le script :

cd ~/versantcms 2>/dev/null && git pull || git clone https://codeberg.org/guillaumedg/versantcms.git ~/versantcms
cd ~/versantcms && sudo bash install.sh

Cette commande fonctionne que ce soit une première installation ou une réinstallation. Le dossier~/versantcmsest nécessaire pour les scripts de désinstallation et les mises à jour.

8. Suivez les étapes interactives

Le script vous guide à travers plusieurs écrans.

• Choix de la langue
• Vérification de la RAM (proposition de swap si < 1.5 Go, ce qui permet une installation plus rapide si votre VPS a peu de RAM)
• Nom du projet (sans espaces)
• Nom de domaine (le script vérifie automatiquement si vous avez bien configuré le pointage du domaine vers votre VPS/serveur)
• Préfixe et mot de passe de l'adresse email (il s'agira de la première adresse email configurée sur votre VPS/serveur)
• Ports de l'application et de PostgreSQL (acceptez les valeurs par défaut, le script détecte automatiquement les ports disponibles)
• Installation de Postfix — deux écrans : écran 1, choisissez « Internet Site » ; écran 2, remplacez le nom suggéré par votre nom de domaine (ex: renseigner crashout.fr, et non pas server1.crashout.fr)
• Configuration de la signature DKIM (automatique)
• Build de l'image Docker
• Lancement de PostgreSQL et migrations
• Démarrage de l'application
• Proposition d'installer Nginx + SSL automatiquement
• Récapitulatif final avec le lien secret d'accès à votre panel admin ainsi que les enregistrements DNS à configurer pour votre serveur mail

9. Dernière étape de l'installation : Configurez votre serveur mail

Votre serveur mail ne sera pleinement opérationnel qu'après avoir ajouté les enregistrements DNS suivants dans le tableau de bord de votre registraire :

La clé publique DKIM complète vous est donnée dans le récapitulatif en fin d'installation.

Ces enregistrements sont nécessaires pour que vos emails arrivent dans la boîte de réception et non dans les spams. Les valeurs exactes vous sont données à la fin du script d'installation.

10. Créez votre compte admin

Ouvrez l'URL secrète dans votre navigateur. Vous arrivez sur la page d'onboarding :

• Choisissez « Nouvelle installation » (pour faire une restauration, voir section Sauvegarde et Restauration
• Renseignez le titre de votre site, votre nom d'auteur, votre email (celui que vous utiliserez pour vous connecter, vous pouvez utiliser une adresse mail personnelle, pas celle que vous venez de configurer) et un mot de passe
• Validez — vous êtes redirigé vers le tableau de bord

Si vous avez correctement configuré votre serveur mail, vous devriez avoir reçu un email de confirmation de la part de l'adresse mail que vous avez configuré. Ce mail contient le lien secret d'accès à votre panel admin.

Sauvegarde et Restauration

Générer une sauvegarde

Depuis votre panel admin, allez dans Paramètres → Sécurité, puis cliquez sur Générer une sauvegarde. Le fichier .zip contenant votre base de données et vos fichiers uploadés sera téléchargé sur votre appareil.

Restaurer après une réinstallation

Après avoir réinstallé une instance Versant (via le script d'installation), ouvrez le lien secret de votre panel admin. Sur la page d'onboarding, choisissez « Restaurer une sauvegarde », sélectionnez le fichier .zip téléchargé précédemment, et validez. Toutes vos données seront restaurées. Attention : vous devrez vous connecter avec le dernier mail et mot de passe que vous utilisiez avec l'instance restaurée.

Mises à jour

Mettre à jour votre instance Versant est un jeu d'enfant. Vous pouvez le faire en un clic depuis votre panel d'administration.

1. Dans le panel admin, allez dans Paramètres → Mise à jour
2. Cliquez sur Vérifier les mises à jour
3. Le système détecte automatiquement la dernière version disponible
4. Si une nouvelle version est disponible, cliquez sur Mettre à jour

Le script rebuild l'image Docker et redémarre l'application automatiquement. Vous n'avez rien d'autre à faire.

Désinstallation

Connectez-vous à votre serveur :

ssh root@<IP_de_votre_VPS>

Puis lancez le script de désinstallation :

cd ~/versantcms && sudo bash uninstall.sh

Le script vous demande de confirmer le nom du projet et le domaine, puis supprime les conteneurs, volumes, dossier d'installation, et propose de nettoyer Postfix et les clés DKIM. Toutes les adresses mail liées à ce site seront également supprimées.

Désinstallation manuelle (non recommandée) :

# Stopper les conteneurs et supprimer les volumes
docker compose down -v

# Supprimer le dossier d'installation
cd ~ && rm -rf ~/sites/votre-projet

# Nettoyer l'alias Postfix
sudo sed -i '/@votre-domaine/d' /etc/postfix/aliases
sudo newaliases

# (optionnel) Supprimer les images inutilisées
docker system prune -a -f

Développement local

Vous pouvez tester Versant en local sur votre ordinateur, sans nom de domaine ni hébergeur.

Installation locale

Sur votre ordinateur, ouvrez un terminal depuis le dossier de votre choix puis clonez le dépôt et lancez le script :

git clone https://codeberg.org/guillaumedg/versantcms.git mon-blog
bash install-local.sh

Le script génère automatiquement le .env, trouve les ports libres, lance Docker et Mailpit, puis affiche le lien secret du panel d'administration.

Désinstallation locale

Pour supprimer votre instance locale, ouvrez un terminal depuis le dossier du projet et exécutez :

bash uninstall-local.sh