README

A complete backup, export and import system for Flarum 2.x

About the Project

Backup & Migration is a full-featured backup and migration extension I've been building for Flarum, inspired by All-in-One WP Migration but written from scratch with a Flarum-native format. It bundles your forum into a single portable .flarum file — database, uploads, storage, and any installed extensions (workbench or vendor) — and restores it on the same install or a different one with one click.

It started from my own need to migrate forums between hosts without the manual mysqldump-and-zip dance, and grew into a complete suite covering encryption, cross-server transfer, per-extension picking, and automatic URL rewriting.

✨ Highlights

• Single portable .flarum file — custom streaming format (not .wpress, not zip), forward-only so multi-GB backups never need to fit in memory
• Pick what to bundle — database, public/assets, storage, and individual extensions, with a tag on each row showing whether it lives in workbench/ or in vendor/ (composer-managed)
• composer.json + composer.lock travel along — vendor extensions stay reproducible on the destination
• Resumable, chunked progress on both export and import (~4 MB per HTTP request), with live progress bars and an upload % indicator
• Optional asymmetric encryption — libsodium hybrid scheme: sealed-box wraps a per-archive XChaCha20-Poly1305 stream key. Public key in the database, private key only in config.php
• Cross-server transfer — encrypt to a foreign public key, paste the matching private key at import time
• Automatic URL rewriting — the source URL is recorded in the archive header and rewritten across settings, posts.content and posts.parsed_content when restoring on a different host
• Selectable restore — per-section and per-extension checkboxes populated from the archive's manifest
• Foreign-key-safe restore — disables FK checks per tick so DDL referencing not-yet-created tables succeeds without ordering dance
• Smart pruning while scanning (node_modules, .git, .idea, nested vendor/…) so workbench scans stay seconds-fast
• Dedicated "you've been logged out" screen when a DB restore replaces the admin's session

🛠️ Technologies

• PHP 8.1+ — resumable export / import jobs, libsodium crypto, MySQL dumper
• TypeScript + Mithril — admin panel UI
• LESS — styling (theme-aware via Flarum's CSS variables)
• libsodium — sealed-box + secretstream chunked encryption

Installation

composer require ramon/backup
php flarum migrate
php flarum cache:clear

Then enable Backup & Migration under the Extensions page in the admin panel.

Links

• GitHub: github.com/ram0ng1/backup
• Packagist: packagist.org/packages/ramon/backup
• Issues: github.com/ram0ng1/backup/issues
• Donate: Stripe

License

MIT

Built with ❤️ by Ramon Guilherme

A personal project focused on making it easier to back up, move and restore Flarum communities — without leaving the admin panel.