Flarum Migration: Moving to a New Server, New Domain, and New Database Without Losing Your Mind

Let me save you a few hours of rage-googling: tar -czf * and mysqldump everything is a one-way ticket to HTTP 500 hell. Been there, done that, bought the T-shirt.

This post is the no-BS, step-by-step guide I wish I had when I had to migrate Flarum to a new server, change the Flarum domain, and swap the Flarum database—all in one evening. Follow it and you’ll be back online before the pizza arrives.

1. Pack Only What Actually Matters

Database – posts, users, config, the whole truth.
public/assets – avatars, uploads, logos.
extensions/ – any local extensions you installed.
storage/formatter & storage/less – compiled CSS/LESS; if you skip them your forum will look like 1998.

Leave behind:

vendor/ – composer will rebuild it.
storage/cache, sessions, views – stale junk that loves to 500 you.
config.php – it’s full of absolute paths and the old domain; we’ll generate a clean one later.

2. Back Up the Safe Stuff

# SSH into the old box
cd /var/www
tar czf flarum_safe.tar.gz \
  flarum/public/assets \
  flarum/storage/logs \
  flarum/storage/formatter \
  flarum/storage/less \
  flarum/extensions

mysqldump -u root -p old_db > old_db.sql

Download or scp both files somewhere safe. S3, Dropbox, a USB stick—whatever floats your boat.

3. Spin Up a Fresh Flarum on the New Server

Provision a new VPS with Nginx + PHP 8.x + MySQL 8 (or MariaDB 10.6+).
Create a new site and database. Do not point DNS yet; use a temporary hostname or raw IP.

Install Flarum cleanly via Composer:

composer create-project flarum/flarum . --stability=beta

Run the web installer once. This creates a brand-new config.php with the correct new database credentials.

4. Restore Your Stuff

# SSH into the new box
cd /var/www/flarum
tar xzf /root/flarum_safe.tar.gz
mysql -u root -p new_db < /root/old_db.sql

Notice we didn’t overwrite vendor/ or config.php. That’s the magic sauce.

5. Update `config.php` for the New World

Open config.php and update the obvious suspects:

'url' => 'https://newdomain.com',
'database' => [
    'host'   => '127.0.0.1',
    'database' => 'new_db',
    'username' => 'new_user',
    'password' => 'new_pass',
],

If your absolute paths changed (they probably did), don’t touch paths—Flarum figures them out automatically.

6. Rebuild & Clean House

composer install --no-dev -o
php flarum migrate
php flarum cache:clear

If migrate says “Nothing to migrate,” you’re golden. If an extension throws a fit, reinstall it:

composer require vendor/extension-name
php flarum cache:clear

7. DNS, HTTPS, and Victory Lap

Point your new domain’s A record to the new server IP.
Grab a Let’s Encrypt cert (Certbot or your panel’s one-click button).
Update config.php to https:// and clear cache one last time.

8. Quick Troubleshooting Cheat Sheet

Symptom	Cause	Fix
Blank page / 500	Stale cache	rm -rf storage/cache/* && php flarum cache:clear
CSS/JS broken	assets folder missing	re-copy `public/assets`
Extension missing	vendor mismatch	composer require vendor/package
Avatar 404	old URL in config	update `'url'` in config.php

Done. Seriously, Stop Overthinking It

Follow the steps above and migrating Flarum to a new server, new domain, and new database is a 30-minute job—mostly waiting for DNS propagation. Now go deploy something fun instead of debugging 500 errors.

If you hit a wall, ping me on Flarum Discuss. We’ve all been there.