How to Deploy Flarum on a VPS

copysudo apt-get update && sudo apt-get -y upgrade
sudo apt-get install -y curl openssl ufw dnsutils unzip caddy composer mariadb-server \
  php-fpm php-mysql php-curl php-dom php-gd php-mbstring php-xml php-zip
php -v | head -1

copyadduser deploy
usermod -aG sudo deploy

copysudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw --force enable

#Create the database

Create a database and a dedicated user, with a random password held in a shell variable for the next step. The guard makes the step safe to re-run: regenerating the password for an existing user would break the install.

copyif [ ! -f /var/www/flarum/config.php ]; then
  DBPASS=$(openssl rand -hex 16)
  sudo mariadb -e "CREATE DATABASE IF NOT EXISTS flarum CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
    CREATE USER IF NOT EXISTS 'flarum'@'localhost' IDENTIFIED BY '$DBPASS';
    ALTER USER 'flarum'@'localhost' IDENTIFIED BY '$DBPASS';
    GRANT ALL ON flarum.* TO 'flarum'@'localhost';"
fi
sudo mariadb -e "SHOW DATABASES LIKE 'flarum';"

#Install Flarum

Flarum is installed with Composer into /var/www/flarum. This is the same command as upstream's install guide; it fetches the current stable release:

copysudo mkdir -p /var/www/flarum && sudo chown "$USER": /var/www/flarum
cd /var/www/flarum
[ -f composer.json ] || composer create-project flarum/flarum . --no-interaction
ls

Now run Flarum's installer from the command line, which skips the web wizard and keeps the admin password out of a browser form. Set your forum's address first (this guide uses forum.example.com; replace it with yours):

copycd /var/www/flarum
DOMAIN=forum.example.com
ADMIN_PASS=$(openssl rand -hex 12)
if [ ! -f config.php ]; then
cat > install.yml <<EOF
debug: false
baseUrl: https://$DOMAIN
databaseConfiguration:
  driver: mysql
  host: localhost
  port: 3306
  database: flarum
  username: flarum
  password: "$DBPASS"
  prefix: ""
adminUser:
  username: admin
  password: "$ADMIN_PASS"
  email: admin@$DOMAIN
settings:
  forum_title: My Forum
EOF
php flarum install --file install.yml
rm -f install.yml
echo "admin password: $ADMIN_PASS"
fi
ls config.php

Write the admin password down now: it is printed once and not stored in plain text anywhere. Then hand the directory to the PHP user, which needs write access to it (notably storage/ and public/assets/), and add the scheduler that Flarum extensions rely on:

copysudo chown -R www-data:www-data /var/www/flarum
echo '* * * * * www-data cd /var/www/flarum && php flarum schedule:run >> /dev/null 2>&1' \
  | sudo tee /etc/cron.d/flarum

#HTTPS + domain

Create an A record for your forum's hostname (say forum.example.com) pointing at the server's public IP, and confirm it resolves before requesting a certificate:

copydig +short forum.example.com

Caddy replaces the usual nginx or Apache setup: one site block serves the public directory, hands PHP to PHP-FPM, and gets its own certificate. See Automatic HTTPS with Caddy for how that works. Replace the whole Caddyfile (/etc/caddy/Caddyfile) and restart Caddy:

copysudo tee /etc/caddy/Caddyfile >/dev/null <<EOF
forum.example.com {
    root * /var/www/flarum/public
    encode zstd gzip
    php_fastcgi unix//run/php/php-fpm.sock
    file_server
}
EOF
sudo systemctl restart caddy

Caddy requests the certificate on the first visit and renews it on its own. Open https://forum.example.com and confirm the padlock. Check the forum's API answers too:

copycurl -s https://forum.example.com/api | head -c 120; echo

#First login and hardening

Sign in as admin with the password the installer printed, then:

1. Open the Administration panel from your user menu and set the forum title, description and welcome banner.
2. Under Mail, configure SMTP. Without it Flarum cannot send password resets or notifications, and a forgotten admin password becomes a database job. A transactional mail provider's free tier is plenty.
3. Change the admin email from the placeholder address to one you control.
4. Review Settings → Registration and decide whether sign-ups need email confirmation; forums that are open to the public attract spam fast.
5. Keep extensions to the ones you need. Each is third-party PHP running with your forum's privileges, and each one is a future upgrade to keep compatible.

#Backups

State lives in two places: the database and the files Flarum writes (config.php, uploaded avatars and attachments under public/assets, and storage). Back up both. Start with a logical database dump:

copycd ~
sudo mariadb-dump --single-transaction flarum > flarum-db-$(date +%F).sql
chmod 600 flarum-db-$(date +%F).sql
test -s flarum-db-$(date +%F).sql && ls -lh flarum-db-*.sql

Then archive the files. The archive holds config.php, which contains the database password, so both backup commands restrict their files to the owner:

copycd ~
sudo tar czf flarum-files-$(date +%F).tar.gz -C /var/www/flarum config.php public/assets storage
sudo chmod 600 flarum-files-*.tar.gz
ls -lh flarum-files-*.tar.gz

Copy both off the server (object storage, another machine, anywhere that survives this VPS dying) and run the pair from cron. A backup you have never restored is a guess, so prove the dump on a scratch database. It should report a non-zero user count:

copycd ~
sudo mariadb -e "DROP DATABASE IF EXISTS flarum_restore; CREATE DATABASE flarum_restore;"
sudo mariadb flarum_restore < flarum-db-$(date +%F).sql
sudo mariadb -N -e "SELECT COUNT(*) FROM flarum_restore.users;"
sudo mariadb -e "DROP DATABASE flarum_restore;"

For a real restore onto a new server, redo the install steps through the composer create-project command (skip the installer), create the database and user, load the dump into flarum, unpack the files archive over /var/www/flarum, set the ownership again and reload Caddy.

#Upgrades

Flarum upgrades are Composer updates. Read the release notes first, take a backup (previous section), and check that every extension you run supports the new version. Then, as the web user:

copycd /var/www/flarum
sudo -u www-data env COMPOSER_HOME=/var/www/flarum/storage/.composer \
  composer update --prefer-dist --no-dev -a --with-all-dependencies --no-interaction
sudo -u www-data php flarum migrate
sudo -u www-data php flarum cache:clear

A minor release is usually painless. A major release is a project of its own: extensions must be updated or replaced first, so follow upstream's upgrade guide step by step instead of running a blanket composer update. If an upgrade breaks the forum, restore the database dump and the files archive and you are back where you started.

#Troubleshooting

A blank page or a 500 error. Look at /var/www/flarum/storage/logs/ first; Flarum writes the real exception there. The usual causes are wrong ownership (re-run the chown -R www-data:www-data command) or a PHP extension missing from the apt-get install list.

Caddy returns 502. PHP-FPM is down or the socket path is wrong. Run systemctl status php*-fpm and check that /run/php/php-fpm.sock exists; the version-independent path is a symlink the Ubuntu package maintains.

Caddy never gets a certificate. Confirm dig +short forum.example.com returns the server's IP and that your provider's network-level firewall, not just ufw, allows inbound 80 and 443. A blocked port 80 silently breaks the ACME challenge.

The forum loads but without styling, or links point at the wrong address. baseUrl in config.php must match the address visitors use, including https. Edit it, then run sudo -u www-data php flarum cache:clear.

Extensions can't be installed from the admin panel. Flarum's own panel does not install packages; extensions are added with composer require as the web user, then enabled in the admin panel.

#Verification + next steps

Not exercised in our test run: the new-user step and the DNS check against your real domain (we ran on a throwaway box with a temporary hostname).

You're done when https://forum.example.com loads with a valid certificate, you can sign in as admin, php flarum commands run as www-data without permission errors, outgoing mail works from the admin panel's test, and you have restored a backup into a scratch database at least once.

From there, create your tags and categories, pick a theme and an extension or two, and invite your first members. For the ranked server picks and the app's catalog details, see Best VPS for self-hosting and the Flarum entry.