How to Migrate a Flarum Forum to a New Host — Full Checklist (2026)

A Flarum forum is more portable than it looks: one database, one uploads directory, one config.php, and a composer.json that describes every extension you run. Move those four things correctly and your forum arrives intact. Miss one and you'll find out from your members. Here's the full checklist.

What a Flarum forum actually consists of

1. The database — every discussion, post, user, and setting
2. Uploads — avatars, attachments, logos (location varies by your upload extension; check before assuming public/assets)
3. config.php — database credentials and the forum URL
4. composer.json / composer.lock — your exact extension set and versions. This file is why Flarum migrations are reproducible: the new server can rebuild your precise installation with one command.

Custom themes/CSS live in the database (Appearance settings), so they travel with it — but if you've modified files on disk directly, note those separately.

Step by step

1. Freeze and back up

Put the forum in maintenance mode so the database stops changing under you. Then export everything:

mysqldump -u USER -p DATABASE > forum-backup.sql
tar czf uploads.tar.gz public/assets   # plus your upload extension's dir

Copy config.php, composer.json, and composer.lock too. Verify the SQL dump is non-empty and recent before going further — a migration is exactly the wrong moment to discover your backup habit was aspirational.

2. Build the new environment

On the new host: same major PHP version (or newer), MySQL/MariaDB, and Composer. Recreate the installation from your dependency file:

composer install   # with your composer.json/lock in place

This pulls Flarum core and every extension at your pinned versions — no hunting through an extensions list by hand.

3. Import data

• Import the SQL dump into the new database
• Unpack uploads into the matching paths
• Update config.php with the new database credentials
• Run php flarum migrate to apply any pending migrations, then php flarum cache:clear

4. The gotchas that actually break migrations

• The url in config.php. If it still points at the old domain or a temporary IP, assets 404 and redirects loop. This is the single most common migration failure.
• PHP version drift. An extension that ran on the old server's PHP may not support the new one. Composer will tell you — at install time, not after cutover, which is why step 2 comes before DNS.
• Email. New server, new IP reputation. Re-verify your SMTP settings and SPF/DKIM records before members notice password resets aren't arriving.
• File permissions. storage/ and the uploads directory must be writable by the web server user.
• HTTPS. Have the certificate issued and tested before you move DNS, not after.

5. Test on the new server before DNS

Point your local machine at the new server (hosts-file override) and click through: log in, post, upload an image, trigger a notification email. Only cut DNS over once that all works.

6. Cut over

Lower the domain's DNS TTL ahead of time, switch the records, keep the old server in maintenance mode (not deleted!) for a week as a fallback. Watch your error logs through the first day of real traffic.

SEO during a host migration

Same domain, same URLs → search engines barely notice a well-executed host move. Just make sure HTTPS works from the first minute, your config.php URL is right (it feeds canonical URLs), and you didn't leave maintenance mode returning errors to crawlers for days. If you're changing domains at the same time — don't. One migration at a time.

Or: have it done for you

Migrations to Link Robins managed hosting are free — you provide a database export, we handle the rest: rebuild, uploads, email setup, HTTPS, and a test URL to verify everything before any DNS changes. It's the same checklist above, just somebody else's responsibility — and afterward, daily off-site backups mean your next migration scare doesn't exist. Get in touch and we'll walk you through it.