Skip to content

User Guide

Installation

Localhost Development Only

Don't use this in Production or anywhere publicly accessible

The containers may take a moment to build. If all goes well, it should immediately connect you to the shell in the Docker container (in /app). The copy of Nitro Porter you downloaded is mounted inside the container. It's the same files.

You must be connected to the Docker container shell to continue below! It is safe to re-run ./bin/setup.sh any time.

You can access phpMyAdmin by visiting localhost:8082 in your browser. Use this to import your database(s). Alternatively, connect a desktop app to MariaDB on localhost:3308 with name & password porter.

Manual Localhost (alternate)

!!! info "Non-Docker Only" — If using Docker (above), skip to "Basic Usage" (below)

If you're doing many migrations or have huge datasets, you may which to avoid Docker. In this case, you need:

  • PHP 8.4+ (CLI-only is fine) with a 256MB+ memory_limit (Nitro Porter will attempt to set this automatically)
  • MariaDB & its PDO driver for PHP
  • Any database connections your platforms require

You can optionally follow my PHP localhost guide for Mac.

With a configured localhost, then:

  1. Get Composer and confirm it is in your PATH.
  2. Add Nitro Porter as a global requirement: composer global require "prosembler/nitro-porter".
  3. Go to the prosembler/nitro-porter directory Composer just created.
    1. On MacOS: cd ~/.composer/vendor/prosembler/nitro-porter
  4. Copy config-sample.php as config.php.
    1. On MacOS or Linux: cp config-sample.php config.php

Basic Usage

  1. Add connections for your source and output to config.php.
  2. See the options with porter --help.

It's normal for a migration to take a while. You're learning a new tool, and you might find bugs from edge cases in you content or more recent changes in the source or target software. If you want free help, expect the back-and-forth to potentially take months depending on the scope of the issues and volunteer availability. If you're in a hurry, contract a developer to manage the process for you. As usual, mind the axiom: "You can have it fast, good, or cheap — pick 2."

Get oriented

Get the "short" names of the packages and connections you want to use.

Run porter list and then choose whether to list:

  • sources [s] — Package names you can migrate from
  • targets [t] — Package names you can migrate to
  • connections [c] — What's in your config (did you make one?)

Note the bolded values without spaces or special characters. Those are the <name> values you need next.

Check support

What can you migrate? Find out!

Run porter show source <name> and porter show target <name> to see what feature data is supported by the source and target. Data must be in both for it to migrate.

Optional: Install the target software

Nitro Porter tends to work the smoothest when you pre-install the new software so its database tables preexist when running the migration. However, it should also work without doing this, so keep reporting issues in either scenario.

Run the migration

Use porter run --help for a full set of options (including shortcodes).

A very simple run might look like: 

porter run --source=<name> --input=<connection> --target=<name>

Example A: Export from Vanilla in example_db to Flarum in test_db: 

porter run --source=Vanilla --input=example_db --target=Flarum --output=test_db

Example B: Export from XenForo in example_db to Flarum in the same database, using shortcodes: 

porter run -s Xenforo -i example_db -t Flarum

Advanced Usage

API data origin (Discord)

The 'pull' command (new in 4.2) enables pulling data from a remote resource like an API. So far, only Discord is supported. To use it, create a Discord bot ("Application") and add it to your Discord server, then update the following fields in your config.php under 'alias' => 'discord',:

  • token with your bot's secret token.
  • guild_id (under extra) with your server ID.

Using 'pull' will populate a localhost database with the data from the Discord server, preparing it for a normal migration. After it completes, follow the above instructions with 'Discord' as the Source and the same Input database.

File transfers

The File Transfer tool (new in 4.0) enables moving files (like attachments & avatars) between platforms by renaming & copying them. To use it, set the following fields in your config.php:

  • source_root is installation folder of the platform you're migrating away from.
  • target_root is the local installation folder to copy files into.
  • target_webroot is the folder under the webroot the platform is installed under when live (if any).

If source_root & target_root are set, Nitro Porter will evaluate whether the source & target support file transfer. As of 4.0, only Xenforo -> Flarum is supported as a proof of concept.

Document targets (NodeBB)

NodeBB runs on MongoDB rather than a SQL database, so Nitro Porter writes the migrated data straight into the Mongo database a NodeBB install is already using.

This target needs the mongodb PHP extension, which the Docker image installs for you. On a manual setup, add it alongside the other required extensions before running composer install.

Install NodeBB first. Unlike a SQL target, there are no tables to fill: NodeBB keeps its content and its configuration, system groups, category permissions and admin account together in one objects collection. Nitro Porter adds to that, renumbering every migrated ID to start above whatever the installer already assigned. Migrating into an empty database gives you a forum with no configuration and no way to log in.

The compose.yml provides mongo (the target store) and nodebb (a v4 install for testing). To run a migration:

  1. Start NodeBB and complete its setup, so the database has an admin and its default configuration.
  2. In config.php, set output_alias to the nodebb (Mongo) connection.
  3. Keep porter_alias on a MariaDB connection. The PORT_ intermediary is always relational, even when the final target is MongoDB.
  4. Run the migration, for example from Vanilla: 
    porter run -s Vanilla -i input -t NodeBb -o nodebb
  5. Restart NodeBB.

After a NodeBB migration

  • Reset permissions. Nitro Porter never migrates permissions; reassign them in the NodeBB admin panel. Migrated users are added to registered-users, so they inherit whatever that group can do.
  • Passwords. NodeBB uses bcrypt. Hashes only carry over if the source used a compatible algorithm; otherwise affected users must reset their password.
  • Re-running. Each run appends. Restore the database from before the last run rather than migrating twice.

Troubleshooting

Command 'porter' not found

Verify Composer is in your PATH with echo $PATH. On MacOS, you should see /Users/{username}/.composer/vendor/bin in there somewhere.

Follow the logs

Nitro Porter logs to porter.log in its installation root (e.g. ~/.composer/vendor/prosembler/nitro-porter on MacOS). Open it with your favorite log viewer to follow along with its progress.

Database table prefixes

Try using the same database as both source & target. Nitro Porter works well with multiple platforms installed in the same database using unique table prefixes.

Currently, it can only use the system default table prefix for targets, but you can customize the source prefix. It uses PORT_ as the prefix for its intermediary work storage. You can safely delete the PORT_ tables after the migration.