Upgrading Self-Hosted Vanilla - Vanilla Success
<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/OAEAEJPQ1TYH/microsoftteams-image-288-29.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/OAEAEJPQ1TYH/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> <p>Follow these steps to upgrade <strong>Higher Logic Vanilla (Vanilla)</strong> when a new stable release is announced. </p><p><strong>📝 NOTE</strong>: These instructions assume you’re using secure file transfer protocol (SFTP) to manually copy files to a server.</p><p><strong>✔️ TIP</strong>: If your database is large (millions of users or comments), consider using <a href="https://success.vanillaforums.com/kb/articles/157-self-hosting-basics#using-maintenance-mode" rel="nofollow noreferrer ugc">maintenance mode</a> before running database updates.</p><ol><li>Back up your database, <code class="code codeInline" spellcheck="false" tabindex="0">.htaccess</code> and <code class="code codeInline" spellcheck="false" tabindex="0">conf/config.php</code> file somewhere safe.</li><li>Delete various files. This is necessary for the upgrade to go smoothly, and to prevent clashes if your filesystem merges directories together. <strong>Delete the following files</strong>.<ul><li>All files in <code class="code codeInline" spellcheck="false" tabindex="0">/dist</code>.</li><li>All files in <code class="code codeInline" spellcheck="false" tabindex="0">/cache</code> (except <code class="code codeInline" spellcheck="false" tabindex="0">.htaccess</code> if you use Apache).</li><li>Any files listed in the version-specific upgrade instructions. <strong><em>If you're upgrading past multiple versions, delete the files from all of the version steps you're skipping (if they exist).</em></strong> For example, if updating from 2.6 to 3.1, upgrade steps for both 2.6 and 2.8 should be completed.</li></ul></li><li>Follow any other version-specific upgrade instructions.</li><li>Upload the new release’s files so they overwrite the old ones.</li><li>Delete all files in <code class="code codeInline" spellcheck="false" tabindex="0">/cache</code> (except <code class="code codeInline" spellcheck="false" tabindex="0">.htaccess</code> if you use Apache).</li><li>Follow all version-specific instructions below. It is <strong>critical</strong> you delete the listed files.</li><li>Go to <code class="code codeInline" spellcheck="false" tabindex="0">example.com/utility/update</code> to run any database updates needed. (404? See next paragraph.) If it fails, try it a second time by refreshing the page.</li></ol><p><strong>✔️ TIP</strong>: If you run into a problem, see <a href="https://success.vanillaforums.com/kb/articles/157-self-hosting-basics#getting-help" rel="nofollow noreferrer ugc">Getting Help</a>.</p><h2 data-id="update-token">Update token</h2><p>On newer versions of Vanilla, your update will request an update token. To find your update token, look in your config for:</p><pre class="code codeBlock" spellcheck="false" tabindex="0">$Configuration['Garden']['UpdateToken'] = '<your token will be here>'; </pre><p>If you don’t find the above in your config, you can add it manually. <em>Use a strong random password generator to generate your update token</em>.</p><h2 data-id="from-vanilla-2.8-or-earlier">From Vanilla 2.8 or earlier</h2><ul><li>Delete <code class="code codeInline" spellcheck="false" tabindex="0">plugins/EmojiExtender</code><ul><li>Directory is now <code class="code codeInline" spellcheck="false" tabindex="0">plugins/emojiextender</code></li><li>The addon key is still <code class="code codeInline" spellcheck="false" tabindex="0">emojiextender</code></li></ul></li><li>Delete <code class="code codeInline" spellcheck="false" tabindex="0">container.html</code></li><li>URL-rewriting is mandatory. Your site should not be using URLs like <code class="code codeInline" spellcheck="false" tabindex="0">?p=/somepath</code>. Refer to the 2.3 upgrade notes for more information.</li><li>Delete <code class="code codeInline" spellcheck="false" tabindex="0">/library/Vanilla/Formatting/Embeds/linkEmbed.twig</code></li></ul><h2 data-id="from-vanilla-2.6-or-earlier">From Vanilla 2.6 or earlier</h2><ul><li>Delete <code class="code codeInline" spellcheck="false" tabindex="0">plugins/Pockets</code> (this is now in core)</li><li>Delete <code class="code codeInline" spellcheck="false" tabindex="0">plugins/akismet</code> (this is now in core)</li><li>Delete <code class="code codeInline" spellcheck="false" tabindex="0">plugins/Debugger</code> (This is no longer maintained and no longer works. See <a href="https://open.vanillaforums.com/addon/debugbar-plugin" rel="nofollow noreferrer ugc">Debug Bar</a> instead.)</li><li>Delete <code class="code codeInline" spellcheck="false" tabindex="0">applications/dashboard/models/class.assetmodel.php</code></li></ul><p><strong>📝 NOTE</strong>: A few addons have been moved out of core; these are no longer maintained, and may represent security holes for your site.</p><ul><li><code class="code codeInline" spellcheck="false" tabindex="0">ButtonBar</code> (use the built-in Rich Editor or Advanced Editor)</li><li><code class="code codeInline" spellcheck="false" tabindex="0">OpenID</code></li></ul><h2 data-id="from-vanilla-2.5-or-earlier%3A">From Vanilla 2.5 or earlier:</h2><ul><li>Delete <code class="code codeInline" spellcheck="false" tabindex="0">plugins/HtmLawed </code>(this is now in core)</li><li>Delete <code class="code codeInline" spellcheck="false" tabindex="0">plugins/Tagging </code>(this is now in core)</li></ul><h2 data-id="from-vanilla-2.3-or-earlier%3A">From Vanilla 2.3 or earlier:</h2><ul><li>Delete <code class="code codeInline" spellcheck="false" tabindex="0">/applications/vanilla/controllers/class.settingscontroller.php</code></li></ul><p><strong>🛑 IMPORTANT</strong>: If your site still uses URLs including <code class="code codeInline" spellcheck="false" tabindex="0">?p=</code>, support for this URL structure has ended. Follow these steps to switch to the simpler format:</p><ol><li>Confirm your server is set up to handle rewrites. On Apache, using the <code class="code codeInline" spellcheck="false" tabindex="0">.htaccess</code> file provided will accomplish this. Additional setup is required on <a href="https://success.vanillaforums.com/kb/articles/221" rel="nofollow noreferrer ugc">nginx</a> and other platforms.</li><li>Test whether it's working by visiting <code class="code codeInline" spellcheck="false" tabindex="0">/discussions</code> . If you see a discussions list (rather than a 404), it's likely set up correctly.</li><li>Open <code class="code codeInline" spellcheck="false" tabindex="0">/conf/config.php</code> and <strong>delete the line</strong>: <code class="code codeInline" spellcheck="false" tabindex="0">$Configuration['Garden']['RewriteUrls'] = false;</code> .</li></ol><p>Your site should immediately switch to “pretty” URL paths instead of using the ‘p’ parameter. If there is a problem, re-add the line to your config and do further troubleshooting.</p><h2 data-id="from-vanilla-2.1-or-earlier%3A">From Vanilla 2.1 or earlier:</h2><ul><li>Update ALL locales you have installed (in <code class="code codeInline" spellcheck="false" tabindex="0">/locales</code>).</li><li>Apache users must update their <code class="code codeInline" spellcheck="false" tabindex="0">.htaccess</code> file.</li><li>Delete <code class="code codeInline" spellcheck="false" tabindex="0">/themes/mobile/views/discussions/helper_functions.php</code></li><li>Delete <code class="code codeInline" spellcheck="false" tabindex="0">/applications/dashboard/views/default.master.php</code></li></ul><h2 data-id="from-vanilla-1.0">From Vanilla 1.0</h2><p>Upgrading from 1.0 (any version) requires a full migration (see <a href="https://success.vanillaforums.com/kb/articles/157-self-hosting-basics#migrating-to-vanilla" rel="nofollow noreferrer ugc">Migrating to Vanilla</a> to learn more). </p><ul><li>Themes and plugins are not compatible. </li><li>Backup your Vanilla 1 data and files completely, and then delete them from your server before attempting to install Vanilla 2.</li></ul> </article> </main>