Installer Discourse sur un VPS avec Docker
Découvrez les prérequis Discourse : RAM et swap, domaine réel, SMTP, app.yml, rebuild, TLS et reverse proxy avec le Docker launcher officiel.
Installer Discourse sur un VPS : un conteneur, un fichier de configuration
Pour installer Discourse sur un VPS, exécutez l’installateur fourni par le projet, répondez à un court assistant, puis attendez la compilation. Discourse est distribué sous la forme d’un conteneur Docker unique qui contient l’application Rails, PostgreSQL, Redis et nginx. Toutes les modifications ultérieures se font dans un seul fichier, /var/discourse/containers/app.yml, et chaque modification est appliquée au site lors d’une nouvelle compilation.
L’installation officielle repose sur discourse_docker : un script shell launcher et un ensemble de modèles YAML. Discourse ne prend pas en charge un fichier Compose que vous rédigeriez vous-même, et le conteneur n’est pas conçu pour être séparé manuellement. Si vous avez l’habitude de exécuter des services sur un VPS avec Docker Compose, attendez-vous à une architecture différente. Il n’y a pas de docker compose up -d ici, et ./launcher rebuild app constitue le déploiement.
Ce dont Discourse a besoin avant de commencer
Quatre prérequis posent souvent problème, et chacun peut vous bloquer avant même d’atteindre la page de connexion.
- Mémoire. Un conteneur exécute PostgreSQL, Redis, Sidekiq et un serveur web Ruby. L’étape de compilation des assets nécessite plus de mémoire que le site en fonctionnement.
- Un vrai nom de domaine. La configuration d’exemple fournie l’indique clairement : « Discourse ne fonctionnera pas avec une simple adresse IP. »
- Un chemin d’envoi des e-mails. L’activation des comptes, la réinitialisation des mots de passe, les invitations d’administration et les e-mails de synthèse sont tous envoyés via SMTP (simple mail transfer protocol).
- Les ports 80 et 443 doivent être libres sur l’hôte, sauf si vous placez volontairement Discourse derrière un proxy déjà en fonctionnement.
Les données de ce graphique
[
{
"label": "Documented minimum",
"ram_gb": 1,
"storage_gb": 10
},
{
"label": "Documented recommended",
"ram_gb": 2,
"storage_gb": 20
}
]La documentation officielle d’installation fixe le minimum à 1 Go de RAM avec du swap et 10 Go d’espace disque. Elle recommande 2 Go de RAM et 20 Go d’espace disque. Interprétez la première ligne comme la quantité nécessaire pour terminer l’installation, et non comme la quantité recommandée pour héberger une communauté. L’écart est important, car le pic de consommation mémoire se produit pendant la compilation, et non en fonction du trafic.
Pointez le domaine vers le serveur avant l’installation
Créez un enregistrement A pour le nom d’hôte que vous utiliserez, puis vérifiez-le depuis le serveur lui-même.
dig +short forum.example.com
curl -4 -s https://ifconfig.coLes deux commandes doivent afficher la même adresse. Elles doivent être cohérentes, car l’assistant d’installation teste la connexion vers votre nom d’hôte. Un enregistrement qui pointe encore ailleurs échoue à ce test. Un enregistrement créé il y a deux minutes peut aussi être encore mis en cache. Attendez donc l’expiration de l’ancien TTL (time to live) au lieu de tenter de contourner l’assistant.
Décidez maintenant si l’enregistrement sera proxifié par un CDN. Un enregistrement proxifié masque l’adresse de votre serveur. La demande de certificat du conteneur échoue alors, car le proxy répond au challenge ACME (automatic certificate management environment) à la place de Discourse. Laissez l’enregistrement non proxifié pour la première installation.
Exécuter l’installateur officiel
Une seule commande installe git, installe Docker avec le script d’installation de Docker, clone discourse_docker dans /var/discourse et démarre l’assistant de configuration.
wget -qO- https://raw.githubusercontent.com/discourse/discourse_docker/main/install-discourse | sudo bashSi Docker est déjà installé sur le serveur et que vous préférez voir chaque étape, effectuez la même opération manuellement.
sudo -s
git clone https://github.com/discourse/discourse_docker.git /var/discourse
cd /var/discourse
./discourse-setupExécutez la commande en tant que root. Lancé par un utilisateur standard, discourse-setup s’arrête immédiatement avec This script must be run as root. Please sudo or log in as root first.. Si Docker n’est pas installé sur le serveur, il s’arrête avec Docker is not installed. Please install Docker first., car le clonage manuel n’installe rien pour vous.
Ce que demande l’assistant d’installation et ce qu’il écrit
En octobre 2026, discourse-setup est un wrapper léger. Il exécute discourse/setup-wizard:release dans un conteneur avec le réseau de l’hôte et le socket Docker monté, afin que l’assistant puisse inspecter la machine qu’il configure. Il demande le nom d’hôte et les adresses e-mail des administrateurs, puis les paramètres SMTP. Il écrit containers/app.yml, puis lance une nouvelle build.
Deux comportements sont à connaître avant de commencer. Si la machine manque de mémoire et ne dispose pas de swap, l’assistant s’arrête et propose d’en créer : le wrapper crée alors un fichier /swapfile de 2 GB, l’ajoute à /etc/fstab, configure vm.swappiness = 10 dans /etc/sysctl.d/30-discourse-swap.conf, puis relance l’assistant. Lorsque l’assistant termine, il affiche Rebuilding app in 5 seconds (Ctrl+C to cancel)... et exécute ./launcher rebuild app sur l’hôte. Cette build prend plusieurs minutes sur un petit VPS. La première est la plus lente, car chaque asset est compilé à partir de zéro.
./discourse-setup --help liste les flags utiles en cas de problème. --skip-rebuild écrit la configuration sans lancer la build, et --skip-connection-test ignore les vérifications DNS et de ports. Utilisez --skip-connection-test uniquement si vous savez déjà pourquoi le test échoue, par exemple lorsque l’hôte se trouve derrière un firewall réseau que vous contrôlez.
Lire app.yml avant la première reconstruction
L’assistant écrit un fichier que vous devez désormais maintenir. Ouvrez-le avec sudo nano /var/discourse/containers/app.yml. Voici les paramètres qui déterminent presque tout.
templates:
- "templates/postgres.template.yml"
- "templates/redis.template.yml"
- "templates/web.template.yml"
- "templates/web.ratelimited.template.yml"
## Uncomment these two lines if you wish to add Lets Encrypt (https)
#- "templates/web.ssl.template.yml"
#- "templates/web.letsencrypt.ssl.template.yml"
expose:
- "80:80" # http
- "443:443" # https
env:
DISCOURSE_HOSTNAME: "forum.example.com"
DISCOURSE_DEVELOPER_EMAILS: "you@example.com"
DISCOURSE_SMTP_ADDRESS: smtp.example.com
DISCOURSE_SMTP_PORT: 587
DISCOURSE_SMTP_USER_NAME: user@example.com
DISCOURSE_SMTP_PASSWORD: "your-smtp-password"DISCOURSE_HOSTNAME est l’adresse à laquelle le site répond. Discourse construit ses liens à partir de cette valeur. Une valeur incorrecte peut donc charger le site une première fois, puis vous rediriger ailleurs. DISCOURSE_DEVELOPER_EMAILS est une liste séparée par des virgules. Ces adresses obtiennent automatiquement les droits d’administration lors de la première inscription. Indiquez votre propre adresse et inscrivez-vous avec celle-ci. C’est ainsi que le premier compte administrateur est créé.
Le fichier stocke votre mot de passe SMTP en clair. Restreignez donc le répertoire avec sudo chmod 700 /var/discourse/containers. Il s’agit également d’un fichier YAML : les espaces sont significatifs pour la configuration. Une clé mal indentée fait échouer la compilation avec une erreur d’analyse et vous laisse sans site. Un piège est documenté dans le fichier d’exemple lui-même. Dans un mot de passe non entouré de guillemets, un # commence un commentaire. Entourez donc de guillemets tout mot de passe qui en contient un.
L’e-mail est l’étape qui fait échouer la plupart des installations
Depuis octobre 2026, l’assistant permet d’ignorer SMTP et d’utiliser les connexions Discourse ID à la place. app.yml comporte aussi un commutateur DISCOURSE_SKIP_EMAIL_SETUP correspondant, décrit comme permettant d’ignorer la validation de la configuration de l’e-mail. Cette option convient pour une première découverte du logiciel. Elle convient mal à une communauté, car sans e-mails sortants, personne ne peut activer un compte ni réinitialiser un mot de passe.
Le problème pratique est que la plupart des fournisseurs de VPS bloquent le port sortant 25. Un serveur de messagerie installé directement sur la machine ne pourra donc pas distribuer les messages. Utilisez un relay authentifié sur le port 587, ou sur le port 465 avec TLS implicite (transport layer security). Pour le port 465, définissez DISCOURSE_SMTP_FORCE_TLS: true, comme le recommande l’exemple de configuration pour ce port. Testez l’accessibilité depuis l’hôte avant de relancer la compilation.
nc -vz smtp.example.com 587Un résultat correct est une seule ligne qui se termine par succeeded!. Une commande qui reste bloquée puis expire indique que le port est bloqué sur le chemin sortant de votre VPS. Aucun réglage Discourse ne peut corriger ce problème. Utilisez un port autorisé par votre fournisseur ou demandez-lui de l’ouvrir.
Une fois le site accessible, envoyez un message de test depuis la page Email de l’interface Admin, puis consultez les onglets Skipped et Bounced sur cette même page. Discourse y enregistre les e-mails qu’il a refusé d’envoyer et ceux que le relay a rejetés. La raison y est indiquée, ce qui est plus rapide que de consulter les journaux.
TLS : laisser le conteneur obtenir son propre certificat
Si Discourse utilise les ports 80 et 443, utilisez son mécanisme intégré d’émission des certificats. Décommentez les deux lignes du template SSL indiquées plus haut, puis reconstruisez le conteneur. Le template pilote acme.sh, stocke les certificats dans le volume partagé sous /shared/ssl, les renouvelle selon une planification interne au conteneur et configure Discourse pour forcer HTTPS.
Le port 80 doit rester accessible depuis Internet pour que cela fonctionne, car le challenge HTTP reçoit sa réponse sur ce port. Un pare-feu qui autorise uniquement 443 permet d’achever le build, mais le certificat n’est jamais émis. Vérifiez le résultat avec ./launcher logs app juste après la reconstruction.
Faut-il placer nginx ou Caddy devant ?
Si Discourse est le seul service web du VPS, ne le faites pas. Le conteneur exécute déjà une instance nginx optimisée. Un second proxy ajoute un saut, un autre certificat à renouveler et une nouvelle source de problèmes liés aux en-têtes.
Placez un proxy devant Discourse lorsque le même VPS héberge d’autres sites. Ajoutez templates/web.socketed.template.yml à la liste des templates, commentez les deux lignes expose et laissez les deux templates SSL commentés. Le conteneur écoute alors sur un socket Unix à l’adresse /var/discourse/shared/standalone/nginx.http.sock et n’utilise aucun port, ce qui libère les ports 80 et 443 pour votre propre proxy.
server {
listen 443 ssl;
server_name forum.example.com;
location / {
proxy_pass http://unix:/var/discourse/shared/standalone/nginx.http.sock:;
proxy_set_header Host $http_host;
proxy_http_version 1.1;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Real-IP $remote_addr;
}
}Les deux-points à la fin de .sock font partie de la syntaxe du socket Unix de nginx. sudo nginx -t refuse la configuration sans ces deux-points. X-Forwarded-Proto est également obligatoire. Discourse écrit des liens absolus. Sans cet en-tête, il génère des liens http:// sur une page HTTPS, et les navigateurs les bloquent comme contenu mixte. Une fois le conteneur configuré avec un socket, la gestion de TLS vous revient. Émettez donc le certificat sur l’hôte avec Certbot sur Ubuntu 24.04 et nginx. Si vous n’avez pas encore choisi de proxy, la comparaison entre nginx, Caddy et Traefik présente les compromis de chaque solution.
Reconstructions, mises à niveau et commandes réellement utilisées
cd /var/discourse
./launcher rebuild apprebuild arrête le conteneur en cours d’exécution, en crée un nouveau à partir de app.yml, puis supprime l’ancien conteneur et démarre le nouveau. Le site est hors ligne pendant toute la durée de la construction. Considérez donc chaque modification de configuration comme une interruption planifiée de quelques minutes.
Les modifications limitées aux valeurs sous env: ne nécessitent pas cette opération. ./launcher destroy app && ./launcher start app recrée le conteneur à partir de l’image déjà construite, ce qui prend quelques secondes. Toute modification sous templates: ou hooks: change l’image elle-même. Elle nécessite donc une reconstruction complète.
Les mises à niveau arrivent de deux façons. Les versions intermédiaires s’appliquent depuis l’interface web à l’adresse /admin/upgrade, grâce au plugin docker_manager que app.yml clone pendant la construction. Les modifications de l’image de base ou des templates proviennent de git.
cd /var/discourse
git pull
./launcher rebuild appLes reconstructions sont souvent à l’origine des échecs sur les petits serveurs, car la compilation des assets représente le pic de consommation mémoire de tout le système. Si une construction s’arrête en cours de route et que dmesg affiche une ligne comme Out of memory: Killed process indiquant un processus ruby, la mémoire est arrivée à saturation pendant la construction, même si le site fonctionnait correctement auparavant. Ajoutez du swap, puis relancez la reconstruction.
./launcher logs app
./launcher enter app
./launcher cleanuplogs affiche la sortie du conteneur et enter ouvre un shell à l’intérieur. cleanup supprime les conteneurs arrêtés ainsi que toutes les images inutilisées datant de plus d’une heure, et Docker vous demande de confirmer chaque nettoyage. L’aide du launcher indique encore qu’il supprime les conteneurs arrêtés depuis plus de 24 heures, mais en octobre 2026 la commande utilise un filtre d’une heure. Exécutez cleanup de temps en temps, car chaque reconstruction conserve l’image précédente et l’espace disque d’un petit VPS finit par manquer sans avertissement.
Sauvegardes et fichier exclu de la sauvegarde
Effectuez les sauvegardes depuis la page Backups de l’interface Admin. L’archive est enregistrée sur l’hôte dans /var/discourse/shared/standalone/backups/default/. La même tâche peut être exécutée depuis un shell.
cd /var/discourse
./launcher enter app
discourse backupdiscourse restore <filename> inverse l’opération, et les restaurations sont refusées tant que vous n’avez pas exécuté discourse enable_restore. Cette protection empêche une commande lancée par erreur d’écraser un forum en production.
Vous devez combler vous-même deux lacunes. L’archive contient la base de données et les fichiers importés uniquement lorsque le paramètre de sauvegarde qui inclut les uploads est activé. Vérifiez donc ce paramètre avant de considérer la sauvegarde comme complète. Elle ne contient jamais app.yml. Une restauration sur un VPS vierge nécessite donc encore votre nom d’hôte et votre configuration SMTP. Copiez également ce fichier hors du serveur.
L’archive se trouve aussi sur le même disque que le site qu’elle protège. Ce n’est pas une sauvegarde. Transférez-la régulièrement vers un autre emplacement.
rsync -avz root@forum.example.com:/var/discourse/shared/standalone/backups/default/ ~/discourse-backups/Ce que coûte un forum actif en RAM
Le bootstrap définit UNICORN_WORKERS et db_shared_buffers à partir de la mémoire et du CPU détectés. La configuration d’exemple limite les buffers partagés au quart de la mémoire totale. Chaque worker Unicorn est un processus Ruby complet. Sidekiq exécute les tâches en arrière-plan en parallèle. L’utilisation mémoire dépend donc du nombre de requêtes simultanées, et non du nombre de membres inscrits. Un forum calme comptant quelques centaines de membres ne représente pas une charge importante. Ce qui partage le serveur compte généralement davantage. S’il s’agit d’une photothèque, les valeurs minimales de RAM mesurées dans la comparaison entre PhotoPrism et Immich vous indiqueront si un rebuild de Discourse dispose encore de suffisamment de mémoire pour se terminer.
Ne dimensionnez pas le serveur à partir d’un chiffre indiqué dans un article, y compris celui-ci. Mesurez votre propre charge.
free -m
docker stats --no-streamUn swap utilisé en permanence avec des pages lentes signifie que la RAM est insuffisante. Une mémoire stable avec des pages lentes indique généralement un autre problème. Consultez donc ./launcher logs app avant de souscrire à une offre plus grande. Ajoutez également un contrôle depuis l’extérieur du serveur. Un forum qui manque de mémoire à 3 h du matin tombe en panne sans forcément générer d’alerte visible. Un monitor Uptime Kuma auto-hébergé sur un hôte séparé vous préviendra avant vos membres.
Quand Discourse n’est pas le bon choix
Discourse est une application volumineuse, dont l’installation est lourde et qui doit être reconstruite après chaque modification d’un paramètre stocké dans app.yml. Ce coût apporte de véritables outils de modération et un moteur de recherche qui reste fonctionnel lorsque les archives deviennent importantes. Pour trente personnes qui veulent simplement disposer d’un espace de discussion, c’est une solution plus lourde que nécessaire. Consultez d’abord la comparaison des logiciels de forum auto-hébergés, puis choisissez Discourse parce que vous avez besoin de ses fonctionnalités, et non parce que c’est le nom que vous connaissiez déjà.
FAQ
Puis-je installer Discourse sur un VPS sans nom de domaine ?
Non. La configuration fournie indique que Discourse ne fonctionnera pas avec une simple adresse IP, et DISCOURSE_HOSTNAME est requis. Discourse construit des liens absolus à partir de ce nom d’hôte. Une adresse IP à cet endroit casse les liens et empêche l’émission du certificat. Créez un enregistrement A avant de commencer, puis vérifiez avec dig +short forum.example.com qu’il pointe vers l’adresse de votre serveur.
Dois-je configurer SMTP pour terminer l’installation ?
Depuis octobre 2026, vous pouvez ignorer cette étape. L’assistant d’installation propose à la place les connexions Discourse ID, et app.yml accepte une option qui ignore la validation de la configuration e-mail. Pour toute utilisation au-delà d’un premier test, configurez-la, car l’activation des comptes et la réinitialisation des mots de passe dépendent toutes deux de l’envoi d’e-mails. Utilisez un relais authentifié sur le port 587 ou 465, car la plupart des fournisseurs de VPS bloquent le port sortant 25.
Pourquoi la reconstruction de Discourse a-t-elle échoué en cours de route ?
La mémoire est la cause la plus fréquente. La compilation des assets pendant la reconstruction nécessite plus de mémoire que le site en fonctionnement. Un serveur qui héberge correctement le forum peut donc tout de même échouer à le reconstruire. Si dmesg affiche Out of memory: Killed process avec un processus Ruby, ajoutez du swap (le swapfile créé par l’assistant fait 2 GB), puis relancez ./launcher rebuild app. Un arrêt sur une erreur YAML indique plutôt une erreur d’indentation dans app.yml.
Discourse doit-il être placé derrière mon propre nginx ou Caddy ?
Seulement si le VPS héberge également d’autres sites. S’il est seul sur le serveur, laissez le conteneur conserver les ports 80 et 443 et émettre son propre certificat. Cela réduit le nombre de composants à gérer. Pour partager la machine, ajoutez templates/web.socketed.template.yml, commentez les lignes expose, puis faites le proxy vers le socket Unix situé à /var/discourse/shared/standalone/nginx.http.sock. Transmettez X-Forwarded-Proto, sinon Discourse génère des liens http:// sur une page HTTPS.
Comment sauvegarder un Discourse auto-hébergé ?
Utilisez la page Backups dans l’interface d’administration, ou exécutez discourse backup après ./launcher enter app. Les archives sont déposées sur l’hôte dans /var/discourse/shared/standalone/backups/default/. Vérifiez que l’option qui inclut les uploads est activée, copiez /var/discourse/containers/app.yml avec l’archive, puis transférez les deux vers une autre machine. Une sauvegarde stockée sur le même disque que le site ne résiste pas à la panne contre laquelle elle doit vous protéger.