Vanilla Porter Guide - HL Vanilla Community
<main> <article class="userContent"> <div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/PA2QSSLCM34W/microsoftteams-image-288-29.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/PA2QSSLCM34W/microsoftteams-image-288-29.png" alt="MicrosoftTeams-image (8).png" height="108" width="1356" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <h2 data-id="migrating-a-forum-to-vanilla">Migrating a forum to Vanilla</h2><p>Vanilla Porter is the <a href="https://open.vanillaforums.com/addon/porter-core" rel="nofollow noreferrer ugc">export tool</a> for converting your legacy forum to Vanilla. The process is four steps:</p><ol><li>Export your old forum data to a special “Porter file”.</li><li>Create a new Vanilla forum.</li><li>Import the Porter file in Vanilla’s Dashboard.</li><li>Verify & finalize your new forum.</li></ol><p>Vanilla Porter <strong>requires</strong> a MySQL database and PHP 5.3+ with zlib support enabled.</p><h2 data-id="before-migrating">Before migrating</h2><p>We recommend these best practices:</p><ol><li><strong>Inform your community</strong> well in advance about the coming transition. Introduce them to Vanilla and communicate why you are migrating and when.</li><li>If possible, <strong>allow moderators time to use Vanilla</strong> and ask questions before migrating.</li><li>Do one or more <strong>test runs</strong> to work out any issues and familiarize yourself with the process.</li><li><strong>Prepare & </strong><a href="https://docs.vanillaforums.com/developer/importing/porter/#redirects" rel="nofollow noreferrer ugc"><strong>test redirects</strong></a> 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 <a href="https://docs.vanillaforums.com/developer/importing/porter/#special-steps-notes" rel="nofollow noreferrer ugc"><strong>Special Steps & Notes</strong></a>.</li></ol><p>Doing these things will help your members, moderators, and yourself have a better migration experience and set good expectations for everyone.</p><p>All set? OK, let’s jump in.</p><h2 data-id="1.-export-old-forum-data">1. Export old forum data</h2><p>Vanlla Porter exports from a database to a special “Porter file” format that Vanilla can import. We currently support <a href="https://docs.vanillaforums.com/developer/importing/support" rel="nofollow noreferrer ugc">these platforms</a>.</p><p>If you have a very large forum (millions of posts), see the <strong>Special Steps & Notes</strong> below before beginning.</p><p>To use it:</p><ol><li><strong>Grab</strong> the <a href="https://open.vanillaforums.com/addon/porter-core" rel="nofollow noreferrer ugc">export tool</a> and unzip it. It will be a single file named <code class="code codeInline" spellcheck="false" tabindex="0">vanilla2export.php</code>.</li><li><strong>Upload</strong> the file to <em>writable</em> web directory on the server with your legacy database. Most forums have a <code class="code codeInline" spellcheck="false" tabindex="0">files</code> or <code class="code codeInline" spellcheck="false" tabindex="0">uploads</code> directory which is an easy place to put it.</li><li><strong>Browse</strong> to vanilla2export.php in your web browser. You should see a “Vanilla Porter” web page.</li><li><em>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.</em></li><li><strong>Enter</strong> information about your forum database into the form and click <strong>Begin Export</strong>. If you can’t remember, try looking at your forum’s configuration file.</li><li><strong>Download</strong> the Porter file it generates</li></ol><p>Got problems? See the <strong>Troubleshooting</strong> section below.</p><h2 data-id="2.-create-a-new-vanilla-forum">2. Create a new Vanilla forum</h2><p>In order to import your data, you will need a fresh installation of <a href="https://open.vanillaforums.com/addon/vanilla-core" rel="nofollow noreferrer ugc">Vanilla</a>. 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.</p><h2 data-id="3.-import-your-data">3. Import your data</h2><ol><li>Place your Porter file (that the export created) in Vanilla’s <code class="code codeInline" spellcheck="false" tabindex="0">uploads</code> folder.</li><li>In Vanilla, click <strong>Import</strong> in the Dashboard.</li><li>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.</li><li>Click <strong>Start Import</strong>.</li><li>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.</li><li>Click <strong>Finish</strong> to cleanup and finalize the import.</li></ol><p>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.</p><h2 data-id="4.-verifying-finalizing-the-import">4. Verifying & finalizing the import</h2><p>These are things to do after your Vanilla import. This includes manually visiting a few “hidden” Dashboard pages just for this process.</p><ol><li><strong>Database Update:</strong> Visit the URL <code class="code codeInline" spellcheck="false" tabindex="0">/utility/update</code> to make any database changes needed. An import can overwrite changes your addons made, so they will be re-applied by this.</li><li><strong>Counters Update:</strong> Visit the URL <code class="code codeInline" spellcheck="false" tabindex="0">/dba/counts</code> to run “counter” updates of things like the number of discussions per category.</li><li><strong>Users:</strong> View your Users page in the Dashboard to verify users were imported correctly and are all assigned to a role.</li><li><strong>Roles & Permissions:</strong> Many imports reset permissions. It is very import you edit each role in turn to review and correct them.</li><li><strong>Default Roles:</strong> Visit the URL <code class="code codeInline" spellcheck="false" tabindex="0">/role/defaultroles</code> to make sure your visitor, default, and applicant roles are assigned correctly.</li><li><strong>Better BBCode:</strong> If you’re coming from a forum that uses BBCode, we recommend grabbing the NBBC plugin from the <a href="https://github.com/vanilla/addons" rel="nofollow noreferrer ugc">Addons repository</a> for improved support.</li><li><strong>Verify Content:</strong> Go through your discussions and categories to make sure your content is complete, ungarbled, and organized correctly.</li><li><strong>Enable & Verify Redirects:</strong> 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 <strong>Redirects</strong> section below for more info.</li></ol><h2 data-id="special-steps-notes">Special Steps & Notes</h2><p>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.</p><h3 data-id="large-forums">Large forums</h3><p>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 <em>any</em> hosting plan.</p><p>For advanced users in these circumstances, copy your database to a localhost installation and run the Porter via the command line. See the <a href="https://github.com/vanilla/porter" rel="nofollow noreferrer ugc">Vanilla Porter repository and README</a> for more information. We likewise recommend importing to a localhost copy of Vanilla and running your verification & finalization steps locally, and repeating the <strong>Default Roles</strong> step after copying the database to production.</p><h3 data-id="attachments">Attachments</h3><p>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 <code class="code codeInline" spellcheck="false" tabindex="0">uploads</code> folder.</p><p>The Porter can export binary blobs for vBulletin. When navigating to the <code class="code codeInline" spellcheck="false" tabindex="0">vanilla2export.php</code> file, add <code class="code codeInline" spellcheck="false" tabindex="0">?avatars=1&files=1</code> to the URL. This will create folders for <code class="code codeInline" spellcheck="false" tabindex="0">attachments</code> and <code class="code codeInline" spellcheck="false" tabindex="0">customavatars</code> that should each be directly copied to Vanilla’s <code class="code codeInline" spellcheck="false" tabindex="0">uploads</code> folder.</p><p>To rename vBulletin’s attachments to have correct extensions, use <code class="code codeInline" spellcheck="false" tabindex="0">filepath=/path/to/attachments</code> in the URL to process them. Renaming phpBB’s attachments requires the special <code class="code codeInline" spellcheck="false" tabindex="0">utilities/phpbb.extensions.php</code> 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 <a href="https://open.vanillaforums.com/" rel="nofollow noreferrer ugc">community forum</a>.</p><h3 data-id="non-mysql-data">Non-MySQL data</h3><p>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.</p><h3 data-id="passwords">Passwords</h3><p>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).</p><p>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: <code class="code codeInline" spellcheck="false" tabindex="0">update GDN_User set HashMethod = 'Reset' where Admin < 1;</code> (the <code class="code codeInline" spellcheck="false" tabindex="0">where</code> 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.</p><h3 data-id="redirects">Redirects</h3><p>For everything to work properly you will probably need to do two redirects: one for the <a href="https://docs.vanillaforums.com/developer/importing/porter/#redirect-the-path" rel="nofollow noreferrer ugc">path</a> and one for the <a href="https://docs.vanillaforums.com/developer/importing/porter/#redirect-the-domain" rel="nofollow noreferrer ugc">domain</a>.</p><p>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.</p><h4 data-id="redirect-the-path">Redirect the path</h4><p>The “path” is everything that comes after the domain. In <a href="http://domain.com/forum/thread.php?id=10&pageNumber=2" rel="nofollow noreferrer ugc"><code class="code codeInline" spellcheck="false" tabindex="0">http://domain.com/forum/thread.php?id=10&pageNumber=2</code></a> that would be <code class="code codeInline" spellcheck="false" tabindex="0">/forum/thread.php?id=10&pageNumber=2</code></p><p>Many legacy platform path redirects can be handled by the <strong>Redirector</strong> plugin in the <a href="https://github.com/vanilla/addons" rel="nofollow noreferrer ugc">Addons repository</a>. Simply enable the plugin. Check the description for what it supports currently.</p><p>You may also create custom redirects, as needed, using the <a href="https://docs.vanillaforums.com/developer/routes" rel="nofollow noreferrer ugc">Routes</a> 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.</p><p>An example of a path redirect would be: <code class="code codeInline" spellcheck="false" tabindex="0">/forum/discussion.php?id=10&pageNumber=2</code> being redirected to <code class="code codeInline" spellcheck="false" tabindex="0">/discussion/10?page=2</code> which is the correct path for the discussion number 10 on page 2.</p><h5 data-id="what-paths-should-be-redirected">What paths should be redirected?</h5><p>It depends greatly on your old forum but here is a list of what <em>should</em> be redirected - Categories / Forums - Discussions / Threads - Comments / Replies - User profiles</p><p>To summarize, all public pages <strong>with relevant content</strong> that were ported to Vanilla <em>should</em> be redirected.</p><h5 data-id="testing-the-redirects">Testing the redirects</h5><p>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.</p><p>Example: If your new forum resides on a different domain you will need to change the domain name like so <a href="http://olddomain.com/forum/discussion.php?id=10&page=2" rel="nofollow noreferrer ugc"><code class="code codeInline" spellcheck="false" tabindex="0">http://olddomain.com/forum/discussion.php?id=10&page=2</code></a> to <a href="http://newdomain.com/forum/discussion.php?id=10&page=2" rel="nofollow noreferrer ugc"><code class="code codeInline" spellcheck="false" tabindex="0">http://newdomain.com/forum/discussion.php?id=10&page=2</code></a> This should result in <a href="http://newdomain.com/forum/discussion.php?id=10&page=2" rel="nofollow noreferrer ugc"><code class="code codeInline" spellcheck="false" tabindex="0">http://newdomain.com/forum/discussion.php?id=10&page=2</code></a> being redirected to <a href="http://newdomain.com/discussion/10?page=2" rel="nofollow noreferrer ugc"><code class="code codeInline" spellcheck="false" tabindex="0">http://newdomain.com/discussion/10?page=2</code></a>.</p><p><em>Note</em>: 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.</p><h5 data-id="redirect-the-domain">Redirect the domain</h5><p>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?):</p><p><a href="http://olddomain.com/..." rel="nofollow noreferrer ugc"><code class="code codeInline" spellcheck="false" tabindex="0">http://olddomain.com/...</code></a> should redirect to <a href="http://newdomain.com/..." rel="nofollow noreferrer ugc"><code class="code codeInline" spellcheck="false" tabindex="0">http://newdomain.com/...</code></a></p><p>It would be the same principle if you were to move your forum on a subdomain:</p><p><a href="http://domain.com/..." rel="nofollow noreferrer ugc"><code class="code codeInline" spellcheck="false" tabindex="0">http://domain.com/...</code></a> would need to be redirected to <a href="http://forumsubdomain.domain.com/..." rel="nofollow noreferrer ugc"><code class="code codeInline" spellcheck="false" tabindex="0">http://forumsubdomain.domain.com/...</code></a></p><p>To help set this up you you can use the <code class="code codeInline" spellcheck="false" tabindex="0">forum-redirector</code> folder in the <a href="https://github.com/vanilla/addons" rel="nofollow noreferrer ugc">Addons repository</a>. *Do not confound the <strong>Redirector</strong> plugin with the <code class="code codeInline" spellcheck="false" tabindex="0">forum-redirector</code> folder.*</p><h2 data-id="troubleshooting">Troubleshooting</h2><h3 data-id="common-problems-using-porter">Common problems using Porter</h3><ol><li>Not placing the file <code class="code codeInline" spellcheck="false" tabindex="0">vanilla2export.php</code> in a web-enabled folder accessible from the Internet.</li><li>Not placing the file <code class="code codeInline" spellcheck="false" tabindex="0">vanilla2export.php</code> in a folder that the web server has permission to <em>write</em> to.</li><li>Attempting to export from an MSSQL database. You must first convert to MySQL. Try the <a href="https://github.com/tburry/dbdump" rel="nofollow noreferrer ugc">dbdump tool</a>.</li><li>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.</li></ol><p>Still having trouble? Ask on the <a href="https://open.vanillaforums.com/" rel="nofollow noreferrer ugc">community forum</a>.</p><h3 data-id="common-problems-while-importing">Common problems while importing</h3><ol><li>Entering a user email address that does not exist in the legacy forum.</li><li>Unzipping the generated porter file. Leave it zipped and <em>do not rename it</em>.</li><li>Not having <code class="code codeInline" spellcheck="false" tabindex="0">zlib</code> installed AND enabled in your PHP install. Confirm this with your host if the file cannot be read.</li><li>Not placing the generated porter file directly in the <code class="code codeInline" spellcheck="false" tabindex="0">uploads</code> folder.</li><li>Attempting to ‘Browse’ for the file rather than selecting it with the multiple choice selector above that.</li></ol><p>Still having trouble? Ask on the <a href="https://open.vanillaforums.com/" rel="nofollow noreferrer ugc">community forum</a>.</p><h3 data-id="data-missing">Data missing</h3><p>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.</p><p><strong>Is it supported?</strong> If so, ask on the <a href="https://open.vanillaforums.com/" rel="nofollow noreferrer ugc">community forum</a>. If you can find the technical reason it didn’t work, please file an <a href="https://github.com/vanilla/porter/issues" rel="nofollow noreferrer ugc">issue on the GitHub repository</a>.</p><p><strong>Not supported?</strong> You can request support be added on the GitHub repository. If you do this, <em>please be prepared to supply a copy of your forum database</em> as a sample. For password support, first create a new user with a password you can share for testing purposes.</p><p>We do accept pull requests for new package support if you create it. Please see the <strong>Contributing</strong> section of the <a href="https://github.com/vanilla/porter" rel="nofollow noreferrer ugc">Vanilla Porter README</a>.</p><h3 data-id="users-cannot-login">Users cannot login</h3><p>See the <strong>Passwords</strong> section under <strong>Special Steps & Notes</strong> above. Use the query there to reset all passwords if necessary.</p><h3 data-id="porter-file-seems-too-small">Porter file seems too small</h3><p>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).</p><h3 data-id="my-legacy-forum-isnt-supported">My legacy forum isn’t supported</h3><p>Weirdo. Just kidding! You can request support (see <strong>Data Missing - Not Supported?</strong> above) or roll your own porter package (see the <a href="https://github.com/vanilla/porter" rel="nofollow noreferrer ugc">repository</a>).</p> </article> </main>