Install Flarum: Modern Lightweight Forum on Nginx and PHP

Flarum is a modern, lightweight forum: a fast single-page interface, mobile-friendly design, tags instead of rigid categories, mentions, likes and real-time-feeling discussions. It’s a good middle ground between classic boards like phpBB and heavier platforms like Discourse, and it runs on ordinary PHP hosting, or a small VPS.

Compare: phpBB (classic, very mature) and Discourse (feature-rich, heavier).

Requirements

PHP 8.1+ (check your Flarum version), with curl, dom, fileinfo, gd, json, mbstring, openssl, pdo_mysql, tokenizer and zip.
MySQL 5.7+/8 or MariaDB 10.x.
Composer. Flarum is installed and extended with it. See Composer.
Shell access (SSH), which a VPS gives you.

sudo apt install nginx mariadb-server php-fpm php-mysql php-curl php-xml php-gd php-mbstring php-zip unzip

1. Database

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

2. Install with Composer

sudo mkdir -p /var/www/flarum && sudo chown $USER:www-data /var/www/flarum
cd /var/www/flarum
composer create-project flarum/flarum .
sudo chown -R www-data:www-data storage public/assets
sudo chmod -R 775 storage public/assets

The web root is public/. Everything else stays outside it.

3. Nginx

Flarum ships a .nginx.conf with the required rules. Include it in your server block:

server {
    server_name forum.example.com;
    root /var/www/flarum/public;
    index index.php;
    client_max_body_size 20M;

    include /var/www/flarum/.nginx.conf;

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

sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d forum.example.com

See Nginx with PHP-FPM and Let’s Encrypt.

4. Web installer

Open https://forum.example.com. The installer asks for the forum title, database credentials (with a table prefix, if you like) and the admin account. It writes config.php in the Flarum root (outside public/). Make sure url in config.php is https://forum.example.com.

5. Email

Admin → Email: choose SMTP and enter your provider’s details, then send a test. Email confirmation and notifications depend on it. See transactional email services.

Extensions

Flarum’s ecosystem lives on Composer:

cd /var/www/flarum
composer require fof/upload           # file uploads
composer require fof/polls            # polls
composer require fof/sitemap          # SEO sitemap
php flarum cache:clear

Enable new extensions in the admin panel. The Extension Manager extension can install extensions from the browser too. The FriendsOfFlarum (fof) collection is a good, maintained source. Check compatibility with your Flarum version before installing.

Queue and scheduler

For better performance (emails and notifications sent in the background) and scheduled tasks:

scheduler cron:

* * * * * cd /var/www/flarum && php flarum schedule:run >> /dev/null 2>&1

queue: install a queue extension (e.g. Redis via blomstra/database-queue or fof/redis), and run the worker under Supervisor or systemd. See Supervisor and crontab.

Anti-spam

Enable email confirmation, add a CAPTCHA or the FoF Stop Forum Spam extension, and use approval queues for first posts. See Fail2Ban for Nginx.

Backups and updates

Back up the database and public/assets (avatars, uploads), storage/ and config.php:

mysqldump --single-transaction flarum | gzip > /backups/flarum-$(date +%F).sql.gz
tar -czf /backups/flarum-files-$(date +%F).tar.gz -C /var/www/flarum config.php composer.json composer.lock public/assets storage

Update:

cd /var/www/flarum
composer update --prefer-dist --no-dev -a --with-all-dependencies
php flarum migrate
php flarum cache:clear

Major Flarum releases (1.x → 2.x) require compatible extensions. Check before upgrading. See backup strategy and updating self-hosted apps.

Quick reference

Task	Command
Install	`composer create-project flarum/flarum .`
Web root	`public/`
Add extension	`composer require vendor/ext`
Migrate	`php flarum migrate`
Clear cache	`php flarum cache:clear`
Scheduler	`php flarum schedule:run` (every minute)

Self-Hosting
Community
PHP