Migrating a forum to Vanilla
Vanilla Porter is the export tool for converting your legacy forum to Vanilla. The process is four steps:
- Export your old forum data to a special “Porter file”.
- Create a new Vanilla forum.
- Import the Porter file in Vanilla’s Dashboard.
- Verify & finalize your new forum.
Vanilla Porter requires a MySQL database and PHP 5.3+ with zlib support enabled.
We recommend these best practices:
Inform your community well in advance about the coming transition. Introduce them to Vanilla and communicate why you are migrating and when.
If possible, allow moderators time to use Vanilla and ask questions before migrating.
Do one or more test runs to work out any issues and familiarize yourself with the process.
Prepare & test redirects from your old forum’s content to its new location. This is important for search engine traffic, preserving links between discussions, and browser bookmarks. More information about this is below under Special Steps & Notes.
Doing these things will help your members, moderators, and yourself have a better migration experience and set good expectations for everyone.
All set? OK, let’s jump in.
1. Export old forum data
Vanlla Porter exports from a database to a special “Porter file” format that Vanilla can import. We currently support these platforms.
If you have a very large forum (millions of posts), see the Special Steps & Notes below before beginning.
To use it:
Grab the export tool and unzip it. It will be a single file named
Upload the file to writable web directory on the server with your legacy database. Most forums have a
uploads directory which is an easy place to put it.
Browse to vanilla2export.php in your web browser. You should see a “Vanilla Porter” web page.
If this is the final export, now is the time to put your legacy forum into read-only mode to prevent posts from being lost during the migration.
Enter information about your forum database into the form and click Begin Export. If you can’t remember, try looking at your forum’s configuration file.
Download the Porter file it generates
Got problems? See the Troubleshooting section below.
2. Create a new Vanilla forum
In order to import your data, you will need a fresh installation of Vanilla. When you do the import, all data in your fresh installation will be overwritten, so make sure you don’t have any discussions you want to keep there. See the README file for help.
3. Import your data
Place your Porter file (that the export created) in Vanilla’s
In Vanilla, click Import in the Dashboard.
Select the file you uploaded. Enter the email of the user from your legacy forum you want to be the superadmin of the new forum. Check “Use my current password”. Leave the password box empty.
Click Start Import.
The import runs a while depending on how much data you have. If it’s more than a million posts, you can make a cup of tea and check Twitter.
Click Finish to cleanup and finalize the import.
Welcome to Vanilla! Notice you are now logged in as the username you entered. The password is the one you created your Vanilla forum with. Below are some more things you should do to get your new forum ready.
4. Verifying & finalizing the import
These are things to do after your Vanilla import. This includes manually visiting a few “hidden” Dashboard pages just for this process.
Database Update: Visit the URL
/utility/update to make any database changes needed. An import can overwrite changes your addons made, so they will be re-applied by this.
Counters Update: Visit the URL
/dba/counts to run “counter” updates of things like the number of discussions per category.
Users: View your Users page in the Dashboard to verify users were imported correctly and are all assigned to a role.
Roles & Permissions: Many imports reset permissions. It is very import you edit each role in turn to review and correct them.
Default Roles: Visit the URL
/role/defaultroles to make sure your visitor, default, and applicant roles are assigned correctly.
Better BBCode: If you’re coming from a forum that uses BBCode, we recommend grabbing the NBBC plugin from the Addons repository for improved support.
Verify Content: Go through your discussions and categories to make sure your content is complete, ungarbled, and organized correctly.
Enable & Verify Redirects: Turn on your 301 redirects to Vanilla. Test old discussion, category, and user profile URLs to make sure you have set up your redirects correctly. See the Redirects section below for more info.
Special Steps & Notes
This part contains nauseating levels of detail about aspects of migrating that hopefully you don’t need to deal with. You’ll get referred here from elsewhere in the docs if you need it.
Forums with over 1 million posts may take a long time to migrate on low-budget hosting plans and cause intense resource usage or downtime while it runs. Forums with over 10 million posts make take a very long time & cause strain on any hosting plan.
For advanced users in these circumstances, copy your database to a localhost installation and run the Porter via the command line. See the Vanilla Porter repository and README for more information. We likewise recommend importing to a localhost copy of Vanilla and running your verification & finalization steps locally, and repeating the Default Roles step after copying the database to production.
File attachments and avatars may be stored in the file system or as binary blobs in the database depending on your platform and configuration. If they are stored in the file system (most common), copy the entire folder directly into Vanilla’s
The Porter can export binary blobs for vBulletin. When navigating to the
vanilla2export.php file, add
?avatars=1&files=1 to the URL. This will create folders for
customavatars that should each be directly copied to Vanilla’s
To rename vBulletin’s attachments to have correct extensions, use
filepath=/path/to/attachments in the URL to process them. Renaming phpBB’s attachments requires the special
utilities/phpbb.extensions.php file in the repository. These are currently advanced user tools and may require consulting the inline documentation in the appropriate package file. If you get stuck, ask on the community forum.
Data in non-MySQL formats (MSSQL, PostgreSQL, XML, CSV, JSON) should first be converted to a MySQL database before using Vanilla Porter or attempting to create a Porter package. For flat file data, we recommend a table per file. Preserving existing column names is preferred whenever possible.
Vanilla natively supports many legacy password schemes for other forums. This means users do not need to reset their password if you’re coming from a platform we support (see the vanilla2export.php file for availability).
If you run into problems, your platform isn’t supported, or want to reset them anyway, you can run this SQL query (via a tool like phpMyAdmin) to reset all passwords:
update GDN_User set HashMethod = 'Reset' where Admin < 1; (the
where clause there prevents resetting your superadmin password). This does not trigger any notification emails; users will be alerted they must reset their password on their next login attempt.
For everything to work properly you will probably need to do two redirects:
one for the path and one for the domain.
When setup properly, users visiting your old forum should be globally redirected to your new Vanilla Forums domain.
Once the user arrives at the new forum, a second redirect will translate the request and forward users to the proper Vanilla URL.
Redirect the path
The “path” is everything that comes after the domain.
http://domain.com/forum/thread.php?id=10&pageNumber=2 that would be
Many legacy platform path redirects can be handled by the Redirector plugin in the Addons repository.
Simply enable the plugin. Check the description for what it supports currently.
You may also create custom redirects, as needed, using the Routes feature in the Dashboard.
Regular expressions can be used to perform pattern matching against incoming paths which will allow you to 301 redirects to the new paths.
An example of a path redirect would be:
being redirected to
which is the correct path for the discussion number 10 on page 2.
What paths should be redirected?
It depends greatly on your old forum but here is a list of what should be redirected
- Categories / Forums
- Discussions / Threads
- Comments / Replies
- User profiles
To summarize, all public pages with relevant content that were ported to Vanilla should be redirected.
Testing the redirects
Once you setup the paths redirects you should test them thoroughly to make sure that everything works fine.
To test you can simple copy an URL from your old forum to the new one.
If your new forum resides on a different domain you will need to change the domain name like so
This should result in
http://newdomain.com/forum/discussion.php?id=10&page=2 being redirected to
Note: For the pages to work properly you need to configure Vanilla to have the same number of comments per page as your old forum had.
Redirect the domain
If the domain where your new forum resides is different than where your old forum was you will need to redirect the domain.
Let’s say that your old domain is olddomain.com and your new domain is newdomain.com (original right?):
http://olddomain.com/... should redirect to
It would be the same principle if you were to move your forum on a subdomain:
http://domain.com/... would need to be redirected to
To help set this up you you can use the
forum-redirector folder in the Addons repository.
*Do not confound the Redirector plugin with the
Common problems using Porter
- Not placing the file
vanilla2export.php in a web-enabled folder accessible from the Internet.
- Not placing the file
vanilla2export.php in a folder that the web server has permission to write to.
- Attempting to export from an MSSQL database. You must first convert to MySQL. Try the dbdump tool.
- Attempting to export from a non-PHP server. Try setting up a tool like MAMP or WAMP on your computer and copying your database there instead.
Still having trouble? Ask on the community forum.
Common problems while importing
- Entering a user email address that does not exist in the legacy forum.
- Unzipping the generated porter file. Leave it zipped and do not rename it.
- Not having
zlib installed AND enabled in your PHP install. Confirm this with your host if the file cannot be read.
- Not placing the generated porter file directly in the
- Attempting to ‘Browse’ for the file rather than selecting it with the multiple choice selector above that.
Still having trouble? Ask on the community forum.
Review the support table included in the vanilla2export.php file (by browsing to it in a web browser and clicking the link) and verify that data is included in that platform.
Is it supported? If so, ask on the community forum. If you can find the technical reason it didn’t work, please file an issue on the GitHub repository.
Not supported? You can request support be added on the GitHub repository. If you do this, please be prepared to supply a copy of your forum database as a sample. For password support, first create a new user with a password you can share for testing purposes.
We do accept pull requests for new package support if you create it. Please see the Contributing section of the Vanilla Porter README.
Users cannot login
See the Passwords section under Special Steps & Notes above. Use the query there to reset all passwords if necessary.
Porter file seems too small
A great deal of data in legacy forums is unneeded, and porter files are compressed significantly. Be sure to do a test import and verify its content before assuming it’s not there. The Vanilla Porter export log will give details on what data has been exported (and how much of each type of data).
My legacy forum isn’t supported
Weirdo. Just kidding! You can request support (see Data Missing - Not Supported? above) or roll your own porter package (see the repository).