Flarum installeren op een VPS: stap-voor-stap handleiding

Flarum installeren op een VPS met PHP en MariaDB

Installeer Flarum op een VPS voor een forum dat draait op PHP en MariaDB, zonder Docker, zonder Ruby en zonder aparte job runner. Dat is de reden om hiervoor te kiezen. Discourse installeren op een VPS betekent een Docker-stack met Ruby, PostgreSQL, Redis en een achtergrondproces, waarbij 2 GB RAM de praktische ondergrens is voordat u back-ups of een mailservice toevoegt. Discourse rechtvaardigt die voetafdruk bij een drukke community met duizenden berichten per dag. Voor een forum met een paar honderd mensen is het een machine die u elke maand betaalt en nooit volledig benut. Flarum past binnen een PHP-stack die u wellicht al draait, waardoor een 1 GB VPS met nginx en MariaDB het kan hosten naast andere applicaties. Als de keuze nog openstaat, behandelt de bredere vergelijking van zelfgehoste forumsoftware de rest van het aanbod.

Deze handleiding richt zich op de installatie van Flarum 1.x, momenteel de 1.8-serie. Sinds augustus 2026 is Flarum 2.0 nog een release candidate, dus 1.8 is de versie om te gebruiken voor een forum waar anderen afhankelijk van zijn. De extensies zijn hier belangrijker dan de kernversie, en de meeste auteurs van extensies zijn nog niet overgestapt naar 2.0.

Wat Flarum 1.8 op de server vereist

De gedocumenteerde vereisten voor Flarum zijn PHP 7.3 of nieuwer, MySQL 5.6+ of MariaDB 10.0.5+, en ofwel nginx of Apache met mod_rewrite. Ubuntu 24.04 levert PHP 8.3 en MariaDB 10.11, dus de distributiepakketten voldoen aan beide vereisten zonder dat er externe repositories nodig zijn. De PHP-extensies die Flarum vereist zijn curl, dom, fileinfo, gd, json, mbstring, openssl, pdo_mysql, tokenizer en zip. U heeft ook shell-toegang nodig, omdat Composer hier niet optioneel is: elke Flarum-extensie is een Composer-pakket en er is geen manier om er een toe te voegen zonder Composer uit te voeren.

Flarum is een standaard PHP-applicatie. Als u al een LAMP-stack op Ubuntu 24.04 draait, is het grootste deel van de volgende twee secties al geïnstalleerd en kunt u deze overslaan tot aan de database.

PHP en de vereiste Flarum-extensies installeren

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

De pakketnamen komen niet één-op-één overeen met de lijst van Flarum. De dom-extensie bevindt zich in php8.3-xml, en fileinfo, json, openssl en tokenizer zijn op Ubuntu gecompileerd in PHP 8.3, waardoor er voor deze onderdelen geen apart pakket geïnstalleerd hoeft te worden. Het commando grep hoort zes regels te tonen en composer --version moet een 2.x-release rapporteren. Een ontbrekende extensie kunt u het beste direct verhelpen, omdat Composer weigert Flarum te installeren zonder de vereiste extensies; de foutmelding geeft hierbij specifiek aan welke extensie ontbreekt:

  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.

Controleer of de PHP-versie voor de command line en de FastCGI Process Manager (PHP-FPM) gelijk zijn. Composer draait onder de command line-binary, terwijl uw forum onder FPM draait; daarom moeten php -v en sudo php-fpm8.3 -v overeenstemmen. Versies kunnen uiteenlopen op een machine waar meerdere PHP-versies uit een externe repository zijn verzameld, waardoor een extensie die voor de ene versie is geïnstalleerd, onzichtbaar is voor de andere.

Maak de database en een specifieke databasegebruiker aan

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;

Geef Flarum een eigen databasegebruiker in plaats van root. De rechten zijn beperkt tot flarum.* en niets anders. Hierdoor kan een SQL-injectie in een extensie van derden uw andere databases niet uitlezen. De tekenset is eveneens van belang: utf8mb4 slaat emoji en niet-Latijnse tekens correct op, terwijl de oudere utf8 van MySQL een drie-byte codering is die een bericht afbreekt bij het eerste teken van vier bytes. Controleer of de gebruiker werkt voordat u verdergaat.

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

Dit hoort flarum te tonen. ERROR 1045 (28000): Access denied for user 'flarum'@'localhost' betekent dat het wachtwoord niet overeenkomt, of dat de gebruiker is aangemaakt voor een andere host dan localhost.

Flarum installeren op een VPS met Composer, vastgezet op 1.8

Maak eerst een systeemgebruiker aan die eigenaar is van de code. Het uitvoeren van Composer als root laat bestanden achter die eigendom zijn van root in vendor/ en storage/, waardoor PHP later zijn eigen cache niet kan schrijven en het forum op elk verzoek reageert met een 500-foutmelding.

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

Dat laatste commando opent een shell als de flarum-gebruiker, in /srv/flarum. Elk commando vanaf hier tot het einde van de handleiding wordt daar uitgevoerd, tenzij het begint met sudo.

composer create-project flarum/flarum:^1.8.0 .

De ^1.8.0-restrictie is de versie-pin. Deze accepteert 1.8.x patch-releases en weigert 2.0, wat gewenst is zolang 2.0 een release candidate is. Composer downloadt het skelet, lost flarum/core en de bijbehorende dependencies op, en levert u public/, storage/, vendor/, composer.json en een flarum command-line script op.

Op een kleine VPS is dit de stap waar zaken misgaan, waarbij twee verschillende fouten op elkaar lijken. PHP Fatal error: Allowed memory size of 134217728 bytes exhausted is de eigen memory_limit van PHP; het plaatsen van COMPOSER_MEMORY_LIMIT=-1 voor het commando verwijdert dat plafond voor één uitvoering. Een kale Killed op een eigen regel zonder PHP-foutmelding is de kernel out-of-memory killer, wat u kunt bevestigen met dmesg | tail. Dat geval betekent dat de machine daadwerkelijk geen RAM meer heeft; voeg in dat geval swap toe. Het verhogen van de PHP-limiet maakt het probleem erger, omdat PHP dan om nog meer geheugen vraagt voordat de kernel ingrijpt.

Waarom alleen /public toegankelijk moet zijn voor het web

De hoofdmap van het project bevat config.php met uw databasewachtwoord in platte tekst, vendor/ met alle dependencies, en storage/ met logs en gecachte sessies. Niets daarvan hoort thuis op het openbare internet. Flarum houdt alles wat via het web toegankelijk moet zijn in één submap, public/, die index.php, een assets/-map en weinig anders bevat. Wijs de root van de webserver aan naar /srv/flarum/public; de rest van de mappenstructuur is dan via HTTP onbereikbaar door het ontwerp, in plaats van door een regel die u moet onthouden.

Wijs de root in plaats daarvan aan naar /srv/flarum en de schade is reëel. Het opvragen van /config.php levert niets nuttigs op, omdat PHP het bestand uitvoert en het alleen een array teruggeeft. Maar /storage/logs/flarum.log geeft een buitenstaander uw stack traces en databasefouten, en /composer.lock vertelt hen precies de versie van elk pakket dat u draait, wat een lijst met bekende kwetsbaarheden is om te proberen.

Geef PHP-FPM een eigen pool

Flarum heeft schrijfrechten nodig voor drie paden: de project root, zodat de installer config.php kan aanmaken; storage/, voor logs en cache; en assets/, voor geüploade avatars en logo's. De bestanden behoren toe aan de flarum-gebruiker, dus de meest nette oplossing is een PHP-FPM-pool die draait als flarum. nginx blijft draaien als www-data en heeft uitsluitend leesrechten.

Schrijf /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

De socket moet worden vermeld als srw-rw---- 1 www-data www-data. Het master-proces draait als root en maakt de socket aan; daarom kan het het eigendom overdragen aan www-data, terwijl de workers draaien als flarum. Als de socket niet aanwezig is, geeft sudo journalctl -u php8.3-fpm -n 30 de melding FPM rejected weer. pm = ondemand start worker-processen pas wanneer er een verzoek binnenkomt, waardoor een rustig forum tussen bezoekers door vrijwel geen geheugen verbruikt.

Het nginx server block

Flarum levert een nginx-fragment in de project root genaamd .nginx.conf. Dit bestand bevat de rewrite-regel, de cache-headers en de compressie-instellingen. Gebruik een include in plaats van de inhoud te kopiëren; zo worden wijzigingen in het fragment bij een Flarum-upgrade automatisch doorgevoerd zonder dat u handmatig bestanden hoeft aan te passen.

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;
    }
}

Sla dit op als /etc/nginx/sites-available/flarum en activeer het vervolgens.

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

nginx -t hoort antwoord te geven op syntax is ok en test is successful. De regel include wordt vaak vergeten. Het weglaten hiervan leidt tot een specifiek symptoom: de voorpagina laadt correct, maar elke link naar een discussie resulteert in een 404-foutmelding van nginx. Flarum routeert een URL zoals /d/1-hello-world intern via PHP. Omdat dit pad geen fysiek bestand op de schijf is, zoekt nginx zonder de try_files $uri $uri/ /index.php?$query_string-regel uit het fragment naar een map genaamd d. Omdat deze niet bestaat, geeft nginx een 404-fout voordat PHP wordt aangeroepen. Apache krijgt dezelfde routering via het .htaccess-bestand dat al in public/ staat; dit werkt alleen als het bijbehorende <Directory>-blok AllowOverride All inschakelt.

Voeg TLS toe voordat u de installer uitvoert

Regel het certificaat nu, niet achteraf. Flarum schrijft tijdens de installatie de eigen base URL naar config.php, waarbij de URL wordt overgenomen van het adres in uw browser. Installeert u via http://, dan begint elke asset-URL die Flarum daarna genereert met http://. Zodra u vervolgens TLS (transport layer security) toevoegt, blokkeert de browser deze verzoeken als mixed content. Het forum laadt dan als platte tekst zonder JavaScript. Doorloop eerst de certbot-configuratie voor Let's Encrypt op nginx, bevestig dat https://forum.example.com een pagina serveert en keer daarna terug.

Indien u al via onversleutelde HTTP heeft geïnstalleerd, is de reparatie slechts één regel. Bewerk /srv/flarum/config.php zodat de sleutel url de waarde 'url' => 'https://forum.example.com', bevat en voer daarna php flarum cache:clear uit als de flarum-gebruiker.

Voer het installatieprogramma uit en beveilig config.php

Open https://forum.example.com in een browser. Het webinstallatieprogramma van Flarum vraagt om de databasenaam, de door u aangemaakte databasegebruiker en het wachtwoord, de forumtitel en uw beheerdersaccount. Het schrijft config.php en maakt de tabellen aan. Zodra dit is voltooid, beperkt u de rechten van het bestand waarin uw databasewachtwoord is opgeslagen.

sudo chmod 640 /srv/flarum/config.php

Het bestand blijft lees- en schrijfbaar voor flarum, de gebruiker waaronder FPM draait, en is onleesbaar voor elk ander account op de server. Controleer vervolgens de installatie vanuit de shell.

php flarum info

Dit toont de core-versie, de PHP-versie, de ingeschakelde extensies, de mail-driver en de gebruikte paden. Dit is het eerste wat u moet uitvoeren wanneer er iets niet naar behoren werkt, en het eerste waar iemand die u helpt om zal vragen.

Waarom e-mails voor registratie en wachtwoordherstel stilletjes falen

Deze sectie bepaalt of uw forum de eerste week overleeft. De eerste twee e-mails die een nieuw forum verstuurt, zijn de registratiebevestiging en het wachtwoordherstel. Beide worden verstuurd op het exacte moment dat een vreemde beslist of uw community legitiem is. Beide falen geruisloos. De persoon die de e-mail niet heeft ontvangen, kan u dit niet laten weten en er verschijnt geen waarschuwing op uw beheerdersdashboard.

Flarum heeft vier mail-drivers, in te stellen onder Administration en vervolgens Email: smtp, mail, mailgun en log. Kies smtp en verwijs deze naar een maildienst die daadwerkelijk bezorgt. De mail-driver geeft het bericht door aan een lokaal sendmail-binary, dat niet aanwezig is op een nieuwe Ubuntu VPS. Het bericht gaat dus nergens heen en er wordt geen foutmelding gegenereerd. De log-driver schrijft de berichtinhoud naar storage/logs/ en verstuurt helemaal niets, omdat deze driver bedoeld is voor ontwikkeling.

Sla de instellingen op en druk vervolgens op de knop Send Test Mail op dezelfde pagina. Die knop is de enige feedbackloop die u heeft, dus gebruik deze voordat u iemand uitnodigt. Als het bericht niet aankomt, lees dan het logbestand.

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

Een geweigerde verbinding, een afgewezen login en een mislukte TLS-onderhandeling komen daar terecht, inclusief de host en poort die werden geprobeerd. Een regel met Connection could not be established with host smtp.example.com betekent dat de poort geblokkeerd of onjuist is. De gebruikelijke oorzaak is dat de provider uitgaand verkeer op poort 25 standaard blokkeert. Poort 587 met het encryptieveld ingesteld op tls is de combinatie die bij vrijwel elke maildienst werkt.

Wanneer mail niet werkt, ziet een bezoeker die zich registreert de algemene foutmelding van Flarum, Oops! Something went wrong. Please reload the page and try again., omdat het verzoek faalt tijdens het versturen van de bevestiging. Hoe dan ook kan die persoon niet inloggen en zal deze u hierover niet benaderen.

Het geaccepteerd krijgen van de mail is een ander probleem dan het versturen ervan. Mail vanaf een VPS-adres zonder SPF- of DKIM-records voor uw domein belandt in de spammap of wordt verwijderd zonder bounce-bericht. Uw logbestand toont dan een succesvolle verzending, terwijl de ontvanger niets ziet. Betrouwbaar mail versturen vanuit zelfgehoste applicaties behandelt welke DNS-records u moet publiceren en welke relay-diensten het overwegen waard zijn.

Extensies zijn Composer-pakketten, dus upgrades zijn een commando

In Flarum is een extensie een Composer-pakket. Er is geen uploadknop en er is geen zip-bestand dat u in een map kunt plaatsen. Dat is een bewuste ontwerpkeuze: versies worden tegen elkaar opgelost, de exacte set wordt vastgelegd in composer.lock, en een extensie die afhankelijk is van een PHP-bibliotheek krijgt die bibliotheek correct geïnstalleerd. De keerzijde is dat het toevoegen ervan drie commando's vereist als de flarum-gebruiker.

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

Schakel deze vervolgens in onder Administration en daarna Extensions. Elk commando voert een specifieke taak uit. composer require plaatst de code op de schijf. php flarum migrate voert eventuele databasemigraties uit die de extensie bevat; dit is hoe deze zijn eigen tabellen aanmaakt. php flarum cache:clear herbouwt de gecompileerde JavaScript- en CSS-bundels die de browser laadt. Het overslaan van de laatste stap zorgt voor de klassieke verwarring: de extensie staat in de lijst, de schakelaar staat aan, maar er verandert niets in de browser, hoe vaak u ook ververst.

Het verwijderen van een extensie werkt in omgekeerde volgorde. Schakel deze eerst uit in het admin-paneel en verwijder daarna het pakket. Flarum laat de tabellen van de extensie bewust staan, zodat het opnieuw inschakelen op een later moment niet leidt tot gegevensverlies. Om deze ook te verwijderen, moet u de migraties terugdraaien voordat u de code verwijdert.

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

De extensie-id in dat commando is de pakketnaam waarbij de slash is vervangen door een koppelteken. Als u liever klikt dan typt, voegt composer require 'flarum/extension-manager:*' een officiële admin-pagina toe die als interface voor Composer dient. Deze voert dezelfde operaties uit als de webgebruiker, heeft hetzelfde geheugen en dezelfde schrijfrechten nodig, en faalt op dezelfde manieren. De opdrachtregel blijft daarom de betrouwbare methode wanneer er iets misgaat.

Waarom composer update weigert om Flarum te upgraden

Het upgraden van Flarum en alle extensies bestaat uit één Composer-commando gevolgd door twee Flarum-commando's. Maak eerst een back-up van de database.

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

Lees de uitvoer in plaats van aan te nemen dat het is gelukt, want het interessante scenario is wanneer Composer weigert om actie te ondernemen:

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

Die melding betekent dat een geïnstalleerde extensie een flarum/core-restrictie bevat die de release waarnaar u wilt overstappen uitsluit. Composer zal de restrictie niet schenden en houdt daarom de gehele installatie op de oude versie, in plaats van een combinatie samen te stellen waarvan de auteur van de extensie heeft aangegeven dat deze niet zal werken. Zoek het verantwoordelijke pakket op.

composer why-not flarum/core 1.8.17

De uitvoer toont elk pakket dat die versie blokkeert en de restrictie die elk pakket hanteert. Vanaf dat punt zijn de opties om te wachten tot de auteur een compatibele release publiceert, of om de extensie te verwijderen en zonder verder te gaan. Dit is de prijs van het Composer-model, en het is de moeite waard om dit te begrijpen voordat u vijftien extensies installeert op een forum waar anderen afhankelijk van zijn. Geef de voorkeur aan extensies die onlangs een release hebben uitgebracht en houd de lijst kort genoeg zodat u deze kunt overzien.

Wat moet u back-uppen

Maak een back-up van de database en de projectmap. Al het overige kan opnieuw worden opgebouwd.

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

Op oudere systemen heet mariadb-dump nog mysqldump; op Ubuntu 24.04 werken beide namen. De database bevat elk bericht, elke gebruiker en elke instelling. De projectmap bevat config.php, composer.json (wat het feitelijke overzicht is van de extensies die u gebruikt) en assets/ met geüploade avatars en logo's. U kunt vendor/ overslaan, omdat composer install dit opnieuw opbouwt vanuit composer.lock, en storage/ zichzelf regenereert. Kopieer beide bestanden van de server af, want een back-up die op dezelfde machine staat als de data die hij moet beschermen, is geen back-up. Herstellen betekent een verse Flarum-installatie van dezelfde versie, composer install, de opgeslagen bestanden terugplaatsen en het SQL-bestand inladen.

FAQ

Kan Flarum draaien op een 1 GB VPS?

Ja, voor een kleine community. Flarum bestaat bij normaal gebruik uit PHP-FPM dat verzoeken afhandelt en MariaDB. Met pm = ondemand bestaan de PHP-workers alleen wanneer iemand de site bezoekt. De piekbelasting treedt op tijdens de installatie zelf: composer create-project lost de volledige afhankelijkheidsgraaf op in het geheugen en is de stap die het vaakst wordt afgebroken door de out-of-memory killer. Voeg een swap-bestand toe voordat u de installatie start, of voer Composer eenmalig uit op een krachtigere machine en kopieer de mapstructuur daarna over.

Waarom geven discussielinks een 404-fout terwijl de hoofdpagina wel werkt?

In uw nginx-serverblok ontbreekt include /srv/flarum/.nginx.conf;. Flarum verwerkt URL's zoals /d/1-hello-world binnen PHP, en dat pad is geen fysiek bestand op de schijf. Zonder de try_files $uri $uri/ /index.php?$query_string-regel uit het fragment zoekt nginx naar een map genaamd d, vindt deze niet en geeft zelf een 404-fout zonder ooit PHP aan te roepen. Op Apache wordt dezelfde routering verzorgd door public/.htaccess, wat wordt genegeerd tenzij het <Directory>-blok AllowOverride All heeft ingesteld.

Waarom verliest mijn forum alle opmaak nadat ik HTTPS heb ingeschakeld?

Flarum slaat de basis-URL op in config.php, gebaseerd op het adres dat u gebruikte tijdens de installatie. Als u via gewone HTTP heeft geïnstalleerd, blijft Flarum http://-asset-URL's genereren. De browser blokkeert deze als mixed content op een HTTPS-pagina, waardoor alleen platte tekst overblijft. Wijzig de url-sleutel in /srv/flarum/config.php naar het https://-adres en voer php flarum cache:clear uit als de gebruiker die eigenaar is van de bestanden.

Waarom ontvangt niemand de bevestigingsmail voor aanmelding?

Controleer eerst de maildriver. De mail-driver vereist een lokaal sendmail-binary dat standaard niet aanwezig is op een nieuwe Ubuntu VPS, en de log-driver schrijft naar storage/logs/ en verstuurt niets. Schakel over naar smtp, gebruik poort 587 met encryptie ingesteld op tls, omdat de meeste providers uitgaand verkeer op poort 25 blokkeren, en klik op Send Test Mail. Als het logboek een succesvolle verzending toont maar de mail toch niet aankomt, ligt het probleem bij de afleverbaarheid in plaats van de configuratie. Publiceer in dat geval SPF- en DKIM-records voor uw domein.

Moet ik Flarum 1.8 of 2.0 installeren?

Installeer 1.8. Sinds augustus 2026 is Flarum 2.0 een release candidate. Belangrijker is dat veel extensies nog steeds een flarum/core-beperking hebben die stopt bij 1.x. Het installeren van 2.0 betekent momenteel dat u een forum draait waarvan de extensies niet gezamenlijk kunnen worden bijgewerkt; dit is precies de fout die composer why-not helpt diagnosticeren. Pin de versie met flarum/flarum:^1.8.0 en bekijk de situatie opnieuw zodra de extensies waar u afhankelijk van bent, 2.0-releases hebben gepubliceerd.