Installer Flarum sur un VPS avec PHP et MariaDB

Installer Flarum sur un VPS avec PHP et MariaDB

Installez Flarum sur un VPS et vous obtenez un forum qui fonctionne avec PHP et MariaDB, sans Docker, sans Ruby et sans gestionnaire de tâches distinct. C’est la raison de le choisir. Installer Discourse sur un VPS implique une stack Docker qui regroupe Ruby, PostgreSQL, Redis et un worker en arrière-plan, et 2 GB de RAM constituent le minimum pratique avant même d’ajouter les sauvegardes ou un service de messagerie. Discourse justifie cette empreinte sur une communauté active qui publie des milliers de messages par jour. Sur un forum de quelques centaines de personnes, c’est une infrastructure que vous payez chaque mois sans jamais l’utiliser pleinement. Flarum s’intègre dans une stack PHP que vous utilisez peut-être déjà, de sorte qu’un VPS de 1 GB avec nginx et MariaDB peut l’héberger à côté des autres services présents. Si le choix n’est pas encore arrêté, la comparaison détaillée des logiciels de forum auto-hébergés couvre les autres solutions.

Ce guide utilise Flarum 1.x, actuellement dans la série 1.8. En août 2026, Flarum 2.0 est toujours une release candidate ; la version à utiliser pour un forum dont dépendent d’autres personnes reste donc la 1.8. Les extensions comptent ici davantage que la version du cœur, et la plupart de leurs auteurs ne sont pas encore passés à 2.0.

Ce que Flarum 1.8 nécessite sur le serveur

La configuration requise documentée par Flarum est PHP 7.3 ou version ultérieure, MySQL 5.6+ ou MariaDB 10.0.5+, ainsi que nginx ou Apache avec mod_rewrite. Ubuntu 24.04 fournit PHP 8.3 et MariaDB 10.11. Les paquets de la distribution répondent donc aux deux exigences sans dépôt tiers. Les extensions PHP requises par Flarum sont curl, dom, fileinfo, gd, json, mbstring, openssl, pdo_mysql, tokenizer et zip. Vous devez également disposer d’un accès shell, car Composer est indispensable ici : chaque extension Flarum est un paquet Composer, et il est impossible d’en ajouter une sans exécuter Composer.

Flarum est une application PHP classique. Si vous utilisez déjà une stack LAMP sur Ubuntu 24.04, la majeure partie des deux sections suivantes est déjà installée. Vous pouvez donc passer rapidement à la base de données.

Installer PHP et les extensions requises par Flarum

sudo apt update
sudo apt install -y nginx mariadb-server composer
sudo apt install -y php8.3-fpm php8.3-cli php8.3-curl php8.3-gd php8.3-mbstring php8.3-mysql php8.3-xml php8.3-zip
php -m | grep -E 'curl|dom|gd|mbstring|pdo_mysql|zip'
composer --version

Les noms des paquets ne correspondent pas exactement à la liste de Flarum. L’extension dom fait partie de php8.3-xml. Les extensions fileinfo, json, openssl et tokenizer sont compilées dans PHP 8.3 sur Ubuntu. Il n’existe donc aucun paquet à installer pour ces extensions. La commande grep doit afficher six lignes et composer --version doit indiquer une version 2.x. Il vaut mieux corriger une extension manquante dès maintenant, car Composer refuse d’installer Flarum sans elle et l’erreur indique le nom de l’extension :

  Problem 1
    - flarum/core[v1.8.0, ..., v1.8.17] require ext-gd * -> it is missing from your system.
      Install or enable PHP's gd extension.

Vérifiez que PHP en ligne de commande et le gestionnaire de processus FastCGI (PHP-FPM) utilisent la même version. Composer s’exécute avec le binaire en ligne de commande, tandis que votre forum s’exécute avec FPM. php -v et sudo php-fpm8.3 -v doivent donc correspondre. Ces versions peuvent diverger sur une machine qui a accumulé plusieurs versions de PHP provenant d’un dépôt tiers. Une extension installée pour une version devient alors invisible pour l’autre.

Créer la base de données et un utilisateur dédié à la base de données

sudo mariadb-secure-installation
sudo mariadb

CREATE DATABASE flarum CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'flarum'@'localhost' IDENTIFIED BY 'use-a-long-random-password';
GRANT ALL PRIVILEGES ON flarum.* TO 'flarum'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Attribuez à Flarum son propre utilisateur de base de données au lieu de root. Les droits accordés couvrent flarum.* et rien d’autre. Ainsi, une faille d’injection SQL dans une extension que vous n’avez pas écrite ne peut pas lire vos autres bases de données. Le jeu de caractères est également important : utf8mb4 stocke correctement les emoji et les scripts non latins, tandis que l’ancien utf8 de MySQL utilise un encodage sur trois octets qui tronque une publication au premier caractère sur quatre octets. Vérifiez que l’utilisateur fonctionne avant de continuer.

mariadb -u flarum -p flarum -e 'SELECT DATABASE();'

La commande doit afficher flarum. ERROR 1045 (28000): Access denied for user 'flarum'@'localhost' signifie que le mot de passe ne correspond pas ou que l’utilisateur a été créé pour un hôte différent de localhost.

Installer Flarum sur un VPS avec Composer, en verrouillant la version sur 1.8

Commencez par créer un utilisateur système propriétaire du code. Exécuter Composer en tant que root laisse des fichiers appartenant à root dans vendor/ et storage/. PHP ne peut alors plus écrire son propre cache, et le forum répond à chaque requête par une erreur 500.

sudo useradd --system --home-dir /srv/flarum --shell /bin/bash flarum
sudo install -d -o flarum -g flarum -m 755 /srv/flarum
sudo -iu flarum

La dernière commande vous ouvre un shell sous l’utilisateur flarum, dans /srv/flarum. Toutes les commandes suivantes, jusqu’à la fin du guide, sont exécutées avec cet utilisateur, sauf si elles commencent par sudo.

composer create-project flarum/flarum:^1.8.0 .

La contrainte ^1.8.0 verrouille la version. Elle accepte les versions correctives 1.8.x et refuse la version 2.0, ce qui est souhaitable tant que 2.0 est une release candidate. Composer télécharge le squelette, résout flarum/core et ses dépendances, puis vous laisse avec public/, storage/, vendor/, composer.json et un script en ligne de commande flarum.

Sur un petit VPS, c’est à cette étape que les problèmes surviennent, et deux pannes différentes peuvent avoir le même aspect. PHP Fatal error: Allowed memory size of 134217728 bytes exhausted est le memory_limit de PHP. Placer COMPOSER_MEMORY_LIMIT=-1 devant la commande supprime cette limite pour une seule exécution. Un Killed seul sur sa propre ligne, sans erreur PHP, indique l’intervention du tueur de processus en cas de manque de mémoire du noyau. Vous pouvez le confirmer avec dmesg | tail. Dans ce cas, la machine n’a réellement plus assez de RAM. Ajoutez donc du swap. Augmenter la limite PHP aggraverait le problème, car PHP demanderait encore plus de mémoire avant l’intervention du noyau.

Pourquoi seul /public doit être exposé sur le Web

La racine du projet contient config.php avec le mot de passe de la base de données en clair, vendor/ avec toutes les dépendances et storage/ avec les journaux et les sessions mises en cache. Rien de tout cela ne doit être accessible depuis Internet. Flarum regroupe tout ce qui doit être accessible sur le Web dans un seul sous-répertoire, public/, qui contient index.php, un dossier assets/ et peu d’autres éléments. Définissez la racine du serveur Web sur /srv/flarum/public. Le reste de l’arborescence est alors inaccessible en HTTP par construction, et non grâce à une règle dont vous devez vous souvenir.

Définissez plutôt la racine sur /srv/flarum et les conséquences sont réelles. Une requête vers /config.php ne renvoie rien d’utile, car PHP exécute le fichier et celui-ci renvoie uniquement un tableau. En revanche, /storage/logs/flarum.log révèle à un visiteur vos traces d’exécution et vos erreurs de base de données, tandis que /composer.lock lui indique la version exacte de chaque package utilisé. Il dispose alors d’une liste de vulnérabilités connues à exploiter.

Attribuer son propre pool à PHP-FPM

Flarum doit pouvoir écrire dans trois chemins : la racine du projet, afin que l’installateur puisse créer config.php ; storage/, pour les journaux et le cache ; et assets/, pour les avatars et les logos téléversés. Les fichiers appartiennent à l’utilisateur flarum. La solution propre consiste donc à utiliser un pool PHP-FPM qui s’exécute sous l’utilisateur flarum. nginx continue de s’exécuter sous www-data et ne fait que lire les fichiers.

Créez /etc/php/8.3/fpm/pool.d/flarum.conf :

[flarum]
user = flarum
group = flarum
listen = /run/php/php8.3-fpm-flarum.sock
listen.owner = www-data
listen.group = www-data
listen.mode = 0660
pm = ondemand
pm.max_children = 10
pm.process_idle_timeout = 30s
php_admin_value[memory_limit] = 256M
php_admin_value[upload_max_filesize] = 16M
php_admin_value[post_max_size] = 17M

sudo systemctl restart php8.3-fpm
ls -l /run/php/php8.3-fpm-flarum.sock

Le socket doit apparaître sous le nom srw-rw---- 1 www-data www-data. Le processus master s’exécute sous root et crée le socket. Il peut donc en attribuer la propriété à www-data, tandis que les workers s’exécutent sous flarum. Si le socket n’existe pas, sudo journalctl -u php8.3-fpm -n 30 affiche la ligne FPM rejected. pm = ondemand ne démarre les workers qu’à l’arrivée d’une requête. Un forum peu fréquenté consomme ainsi presque aucune mémoire entre deux visiteurs.

Le bloc server nginx

Flarum fournit un snippet nginx à la racine du projet, nommé .nginx.conf. Il contient la règle de réécriture, les en-têtes de cache et les paramètres de compression. Incluez-le au lieu de le copier. Ainsi, une mise à niveau de Flarum qui modifie ce snippet est automatiquement prise en compte par votre serveur.

server {
    listen 80;
    listen [::]:80;
    server_name forum.example.com;

    root /srv/flarum/public;
    index index.php;
    client_max_body_size 16M;

    include /srv/flarum/.nginx.conf;

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.3-fpm-flarum.sock;
    }
}

Enregistrez-le sous /etc/nginx/sites-available/flarum, puis activez-le.

sudo ln -s /etc/nginx/sites-available/flarum /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

nginx -t doit répondre à syntax is ok et test is successful. La directive include est souvent oubliée. Son absence produit un symptôme très précis : la page d’accueil se charge correctement, mais chaque lien vers une discussion renvoie une erreur 404 par nginx. Flarum traite une URL comme /d/1-hello-world dans PHP. Ce chemin ne correspond pas à un fichier présent sur le disque. Sans la règle try_files $uri $uri/ /index.php?$query_string du snippet, nginx recherche donc un répertoire nommé d, ne le trouve pas et renvoie une erreur 404 avant même de transmettre la requête à PHP. Apache applique le même routage à partir du fichier .htaccess déjà présent dans public/. Cette configuration ne prend effet que si le bloc <Directory> correspondant définit AllowOverride All.

Ajouter TLS avant d’exécuter l’installateur

Obtenez le certificat maintenant, pas après l’installation. Flarum inscrit sa propre URL de base dans config.php pendant l’installation, en utilisant l’adresse affichée dans votre navigateur. Installez-le via http:// et toutes les URL de ressources générées ensuite par Flarum commenceront par http://. Lorsque vous ajouterez TLS (Transport Layer Security), le navigateur bloquera alors ces requêtes comme contenu mixte, et le forum se chargera sans style, sans JavaScript. Suivez d’abord la procédure de configuration de certbot pour Let's Encrypt avec nginx, vérifiez que https://forum.example.com affiche bien une page, puis revenez ici.

Si vous avez déjà effectué l’installation via HTTP non chiffré, la correction tient en une ligne. Modifiez /srv/flarum/config.php pour que la clé url ait la valeur 'url' => 'https://forum.example.com',, puis exécutez php flarum cache:clear avec l’utilisateur flarum.

Exécuter l’installateur et sécuriser config.php

Ouvrez https://forum.example.com dans un navigateur. L’installateur web de Flarum demande le nom de la base de données, le nom d’utilisateur et le mot de passe de la base que vous avez créés, le titre du forum et votre compte administrateur. Il écrit config.php et crée les tables. Une fois l’installation terminée, restreignez l’accès au fichier qui contient désormais le mot de passe de la base de données.

sudo chmod 640 /srv/flarum/config.php

Le fichier reste lisible et modifiable par flarum, qui est l’utilisateur utilisé par FPM, et reste inaccessible en lecture pour tous les autres comptes du serveur. Vérifiez ensuite l’installation depuis le shell.

php flarum info

Cette commande affiche la version du cœur, la version de PHP, les extensions activées, le pilote de messagerie et les chemins utilisés. C’est la première commande à exécuter lorsqu’un problème survient, et la première information que vous demandera toute personne qui vous aide.

Pourquoi les e-mails d’inscription et de réinitialisation du mot de passe échouent sans message d’erreur

Cette section détermine si votre forum survivra à sa première semaine. Les deux premiers e-mails qu’un nouveau forum envoie sont la confirmation d’inscription et la réinitialisation du mot de passe. Ils partent exactement au moment où un nouvel utilisateur cherche à déterminer si votre communauté est réelle. Tous deux peuvent échouer silencieusement. La personne qui n’a jamais reçu le message ne peut pas vous le signaler, et rien ne devient rouge dans votre tableau de bord d’administration.

Flarum propose quatre drivers de messagerie, configurés dans Administration puis E-mail : smtp, mail, mailgun et log. Choisissez smtp et reliez-le à un service de messagerie qui assurera réellement la distribution. Le driver mail transmet le message à un binaire sendmail local. Celui-ci n’existe pas sur un VPS Ubuntu fraîchement installé. Le message n’aboutit donc nulle part et aucune erreur n’est générée. Le driver log écrit le corps du message dans storage/logs/ et n’envoie rien, car il est prévu pour le développement.

Enregistrez les paramètres, puis cliquez sur le bouton Send Test Mail sur cette même page. C’est la seule boucle de retour disponible. Utilisez-la donc avant d’inviter qui que ce soit. Si le message n’arrive pas, consultez le journal.

tail -n 50 /srv/flarum/storage/logs/flarum.log

Une connexion refusée, une authentification rejetée et un échec de négociation TLS apparaissent tous à cet endroit, avec l’hôte et le port utilisés. Une ligne contenant Connection could not be established with host smtp.example.com signifie que le port est bloqué ou incorrect. La cause habituelle est que le fournisseur bloque par défaut le port sortant 25. Le port 587 avec le champ de chiffrement défini sur tls fonctionne avec presque tous les services de messagerie.

Lorsque la messagerie ne fonctionne pas, un visiteur qui s’inscrit voit la bannière d’erreur générique de Flarum, Oops! Something went wrong. Please reload the page and try again., car la requête échoue pendant l’envoi de la confirmation. Dans tous les cas, cette personne ne peut pas accéder au forum et ne vous écrira pas pour vous le signaler.

Faire accepter le message est un problème distinct de son envoi. Un e-mail envoyé depuis l’adresse d’un VPS, sans enregistrements SPF ou DKIM publiés pour votre domaine, arrive dans le dossier des indésirables ou est supprimé sans aucun message de retour. Votre journal indique alors un envoi réussi, tandis que le destinataire ne voit toujours rien. Envoyer des e-mails de manière fiable depuis des applications auto-hébergées explique quels enregistrements DNS publier et quels services de relais utiliser.

Les extensions sont des paquets Composer : leur mise à niveau se fait donc avec une commande

Dans Flarum, une extension est un paquet Composer. Il n’existe pas de bouton d’envoi ni de fichier zip à déposer dans un dossier. C’est un choix de conception délibéré : les versions sont résolues les unes par rapport aux autres, l’ensemble exact est enregistré dans composer.lock et une extension qui dépend d’une bibliothèque PHP obtient cette bibliothèque correctement installée. En contrepartie, l’ajout d’une extension nécessite trois commandes avec l’utilisateur flarum.

composer require 'fof/upload:*'
php flarum migrate
php flarum cache:clear

Activez-la ensuite dans Administration, puis Extensions. Chaque commande a une fonction distincte. composer require place le code sur le disque. php flarum migrate exécute les migrations de base de données fournies par l’extension, ce qui lui permet de créer ses propres tables. php flarum cache:clear reconstruit les bundles JavaScript et CSS compilés chargés par le navigateur. Si vous ignorez cette dernière étape, vous obtenez le problème classique : l’extension est répertoriée, le bouton est activé, mais rien ne change dans le navigateur, même après plusieurs actualisations.

La suppression d’une extension se fait dans l’ordre inverse. Désactivez-la d’abord dans le panneau d’administration, puis supprimez le paquet. Flarum conserve volontairement les tables de l’extension afin qu’une réactivation ultérieure n’entraîne aucune perte de données. Pour les supprimer également, annulez ses migrations avant de supprimer le code.

php flarum migrate:reset --extension fof-upload
composer remove fof/upload
php flarum cache:clear

L’identifiant de l’extension utilisé dans cette commande est le nom du paquet, avec la barre oblique remplacée par un trait d’union. Si vous préférez cliquer plutôt que saisir des commandes, composer require 'flarum/extension-manager:*' ajoute une page d’administration officielle qui encapsule Composer. Elle exécute les mêmes opérations que l’utilisateur web, nécessite la même mémoire et les mêmes permissions d’écriture, et échoue de la même manière. La ligne de commande reste donc la méthode la plus fiable en cas de problème.

Pourquoi composer refuse de mettre Flarum à niveau

Mettre à niveau Flarum et toutes ses extensions consiste à exécuter une commande Composer, puis deux commandes Flarum. Sauvegardez d’abord la base de données.

composer update --prefer-dist --no-plugins --no-dev -a --with-all-dependencies
php flarum migrate
php flarum cache:clear

Lisez la sortie au lieu de supposer que la mise à niveau a réussi. Le cas intéressant est celui où Composer refuse de modifier quoi que ce soit :

Your requirements could not be resolved to an installable set of packages.

Ce message signifie qu’une extension installée déclare une contrainte flarum/core qui exclut la version vers laquelle vous effectuez la mise à niveau. Composer ne viole pas cette contrainte. Il conserve donc toute l’installation dans l’ancienne version au lieu de construire une combinaison dont l’auteur de l’extension a indiqué qu’elle ne fonctionnerait pas. Recherchez le package responsable.

composer why-not flarum/core 1.8.17

La sortie répertorie chaque package qui bloque cette version, ainsi que la contrainte qu’il déclare. Vous pouvez alors attendre que l’auteur publie une version compatible, ou supprimer l’extension et vous en passer. C’est la contrepartie du modèle Composer. Il est utile de le comprendre avant d’installer quinze extensions sur un forum dont dépendent d’autres utilisateurs. Privilégiez les extensions dont une version a été publiée récemment et gardez une liste suffisamment courte pour pouvoir la lire.

Éléments à sauvegarder

Sauvegardez la base de données et le répertoire du projet. Tout le reste peut être recréé.

mariadb-dump -u flarum -p --single-transaction flarum > flarum-$(date +%F).sql
sudo tar czf flarum-files.tgz -C /srv flarum

Sur les anciens systèmes, mariadb-dump s’appelle mysqldump ; sur Ubuntu 24.04, les deux noms fonctionnent. La base de données contient chaque publication, chaque utilisateur et chaque paramètre. Le répertoire du projet contient config.php, composer.json (qui constitue l’enregistrement réel des extensions que vous exécutez) et assets/, avec les avatars et les logos téléversés. Vous pouvez ignorer vendor/, car composer install le recrée à partir de composer.lock, et storage/ se régénère automatiquement. Copiez les deux fichiers hors du serveur, car une sauvegarde stockée sur la machine qu’elle protège n’est pas une sauvegarde. La restauration nécessite une nouvelle installation de Flarum dans la même version, composer install, la remise en place des fichiers sauvegardés et le chargement du fichier SQL.

FAQ

Flarum peut-il fonctionner sur un VPS de 1 GB ?

Oui, pour une petite communauté. En fonctionnement normal, Flarum utilise PHP-FPM pour traiter les requêtes et MariaDB. Avec pm = ondemand, les workers PHP n’existent que pendant la lecture d’une page. Le pic de consommation se produit pendant l’installation : composer create-project résout l’ensemble du graphe des dépendances en mémoire. C’est l’étape la plus susceptible d’être arrêtée par l’oom-killer. Ajoutez un fichier swap avant l’installation, ou exécutez Composer une fois sur une machine plus puissante, puis copiez l’arborescence.

Pourquoi les liens vers les discussions renvoient-ils une erreur 404 alors que la page d’accueil fonctionne ?

Votre server block nginx ne contient pas include /srv/flarum/.nginx.conf;. Flarum traite dans PHP les URL telles que /d/1-hello-world. Ce chemin ne correspond pas à un fichier sur le disque. Sans la règle try_files $uri $uri/ /index.php?$query_string de l’extrait, nginx recherche un répertoire nommé d, échoue, puis renvoie lui-même une erreur 404 sans appeler PHP. Avec Apache, ce routage repose sur public/.htaccess. Cette directive est ignorée si le bloc <Directory> ne définit pas AllowOverride All.

Pourquoi mon forum a-t-il perdu toute sa mise en forme après l’activation de HTTPS ?

Flarum enregistre son URL de base dans config.php. Cette valeur est récupérée depuis l’adresse utilisée lors de l’exécution de l’installateur. Si vous avez installé Flarum en HTTP simple, Flarum continue de générer des URL d’assets en http://. Le navigateur les bloque alors comme contenu mixte sur une page HTTPS, ce qui laisse uniquement du texte sans mise en forme. Modifiez la clé url dans /srv/flarum/config.php pour utiliser l’adresse https://, puis exécutez php flarum cache:clear avec l’utilisateur propriétaire des fichiers.

Pourquoi personne ne reçoit-il l’e-mail de confirmation de l’inscription ?

Vérifiez d’abord le mail driver. Le driver mail nécessite un binaire sendmail local, absent d’un VPS Ubuntu fraîchement installé. Le driver log écrit dans storage/logs/ et n’envoie aucun e-mail. Passez à smtp, utilisez le port 587 avec le chiffrement défini sur tls, car la plupart des fournisseurs bloquent le port sortant 25, puis cliquez sur Send Test Mail. Si le journal indique que l’envoi a réussi alors que l’e-mail n’arrive toujours pas, le problème concerne la délivrabilité et non la configuration. Publiez donc les enregistrements SPF et DKIM de votre domaine d’envoi.

Dois-je installer Flarum 1.8 ou 2.0 ?

Installez 1.8. En août 2026, Flarum 2.0 est une release candidate. Surtout, de nombreuses extensions déclarent encore une contrainte flarum/core qui s’arrête à la version 1.x. Installer 2.0 aujourd’hui revient à utiliser un forum dont les extensions ne peuvent pas être mises à jour ensemble. C’est précisément le problème que composer why-not permet de diagnostiquer. Figez la version avec flarum/flarum:^1.8.0 et réévaluez la situation lorsque les extensions dont vous dépendez auront publié leurs versions 2.0.