How to Upgrade to VaultWiki 4 (deprecated)
by
, January 25, 2013 at 11:00 PM (111940 Views)
This information only applies when upgrading to VaultWiki 4 Beta 4 and lower. There is a different, safer upgrade process for upgrading to newer versions.
So as you may or may not know, VaultWiki 4 comes with a one-click upgrade system, which theoretically means faster, easier upgrades for users. However, if you already have a VaultWiki 3 installation that you will be upgrading to version 4, the process may not be as easy or straightforward as such a system might suggest.
As I recently was tasked with upgrading the site here at vaultwiki.org to VaultWiki 4, and as many noticed, this was by no means a smooth process or a quick one, I've decided to put this blog together as a reference for users (which includes most existing customers) who will be following a similar upgrade path.
That said, your upgrade will be smoother than mine was. Likely you'll be uploading the files directly to your site and not proxying them from some other location like we do here. A handful of script errors in the upgrade system were already identified and fixed.
Things That May Be Problematic
VaultWiki 3 had a problem with mixed encodings and when trying to reverse lookup articles that were written in different languages. VaultWiki 4 resolves this issue by only allowing one character set in wiki-related tables (UTF-8), and by only allowing one global set of encodings for all articles. As a result, URLs for the same article would be the same regardless of the language selection for the article.
This change had some side effects. VaultWiki 3 had also allowed users to create custom paths for namespaces and to translate those paths for each language. VaultWiki 4 only allows one global custom path for each wiki area where a namespace was imported. So if you had translated paths, they won't work anymore. To avoid significant detriment to Page Rank, you will have to adjust your server configuration in a later step.
Who Can or Should Upgrade
The first release of VaultWiki 4 (Alpha 1) is not entirely complete. There are some features that are disabled. If you use them on your site, be prepared for them to be broken for some time, or opt NOT to upgrade.
- Consider not upgrading right away if you use multiple languages in VaultWiki 3. The interface for modifying the language of wiki pages and for selecting other wiki pages to act as translations of a wiki page is not ready and is not present in VaultWiki 4.
- Consider not upgrading right away if you use wiki parser functions in non-wiki posts. There is functionality in VaultWiki 3 that let users essentially create wiki pages outside of the wiki in places like a regular forum post. This functionality does not yet exist in VaultWiki 4.
- Consider not upgrading right away if you use a lot of polls in your wiki. The interfaces for modifying polls, voting, and displaying results is not ready and is not present in VaultWiki 4.
- Absolutely do NOT upgrade if you are considering changing your attachment storage method from file system to database or vice verse in the near future, unless you make the decision before upgrading. Attachments in VaultWiki 4 are not stored with other forum attachments, and there is not yet an interface to change the storage method once it is set in VaultWiki 4.
Ultimately, if you don't fall into one of these categories, you can probably upgrade safely, but keep in mind that the first few versions of VaultWiki 4 will be Alpha, Beta, then RC releases, so version 4 will not be considered a "stable" release for some time.
Preparing for Upgrade
The following steps should be taken BEFORE uploading any files to your server:
- In AdminCP > Settings > Options > VaultWiki: Server Settings, set "Turn on the Wiki?" to No.
- In AdminCP > Forums & Moderators > Forum Manager, locate the Forum Category that contains all your wiki forums, and set the Display Order to 0. If your wiki forums are not contained in one dedicated parent forum, then skip this step. Do NOT modify the wiki forums themselves.
- In AdminCP > Forums & Moderators > Forum Manager, locate any of your wiki forums that have a Forum Link (would have "(Link)" next to the title), and make sure the path is correct. If you have recently moved to a new server or directory, the value may be wrong. If the URL does not contain the correct wiki path for your installation, the page will not be linked to the wiki forum when you upgrade.
- In AdminCP > Plugins & Products > Product Manager, disable ALL products that have VaultWiki as a dependency. Note: Products and scripts that depend on VaultWiki will need to be completely rewritten for VaultWiki 4 before they can be reactivated.
- In AdminCP > Plugins & Products > Product Manager, disable VaultWiki.
- Absolutely, back up your database. I know that some site admins, like myself, occasionally get brave when installing/upgrading products and don't do this. Please, do NOT skip it this time. And yes, do it now when everything is already turned off. I can't tell you how many times I restored a database that didn't have the prior steps already done, went ahead, and had to restore the database again because I ended up running the upgrade script with nothing disabled.
- If you store your attachments in the file system, navigate to the server location that contains the attachment directory, and create a new folder that will be used only for wiki attachments. Call it something like wiki-attachments, make sure that it's chmod 0777, and that it's owned and grouped by the same user that runs your attachment directory. If the permissions on this folder are wrong, your upgrade won't be successful and you'll have to start over.
Actually Upgrading
Now we can do the easy part, the actual upgrade.
- As usual, log into your account on vaultwiki.org and proceed to the Members tab.
- Next to your license, click Download. From the version drop-down, select the most recent "4.0.0" package (as of this writing, that's Alpha 1), and make sure you choose the download the whole package.
- Unzip the archive and upload the contents of the /upload directory to your forum root directory. If you have the wiki installed on a sub-domain, upload the contents of the /do-not-upload directory to your sub-domain directory, and modify the vw_config.php file so that the paths are correct.
- Edit the file /vault/config.php and make sure the values are correct. The file should be commented sufficiently so that you know what everything is for and what you should put there.
- Navigate to yoursite/vault/install/index.php
- Click "Upgrade." Respond to any prompts that pop-up. If the process seems to hang at all, scroll to the bottom, and check for any error messages.
- When the script is finished, you will be prompted to enter the wiki Admin Panel.
Technically the database is now upgraded and VaultWiki 4 should run now. But...
Immediately After Upgrading
There's still quite a bit to do. The upgrader did its best to convert the VaultWiki 3 values, but a lot of VaultWiki 4 works completely differently and will need a human to review.
- Remove the following files and folders from your server. If you don't do this, you might have database errors doing certain things in the AdminCP since vBulletin automatically scans some directories (like /packages and /includes/xml) and runs code just because it's there. These files are no longer needed:
- /admincp/vaultwiki_bbcode.php
- /admincp/vaultwiki_domain.php
- /admincp/vaultwiki_namespace.php
- /admincp/vaultwiki_protect.php
- /admincp/vaultwiki_setup.php
- /admincp/vaultwiki_style.php
- /admincp/vaultwiki_tools.php
- /admincp/vaultwiki_url.php
- /clientscript/vault/
- /clientscript/ckeplugins/vwimage/
- /includes/xml/bitfield_ces_nwsp_extra.xml
- /includes/xml/bitfield_ces_nwsp_spec.xml
- /includes/xml/cpnav_ces_nwsp_spec.xml
- /includes/xml/cssrollup_ces_nwsp_spec.xml
- /includes/xml/hooks_ces_nwsp_spec.xml
- /modcp/vaultwiki_moderate.php
- /packages/vaultwiki/attach/vaultarticle.php
- /packages/vaultwiki/legacy/
- /packages/vaultwiki/search/type/vaultarticle.php
- /vault/admin/
- /vault/class/
- /vault/cron/
- /vault/dm/
- /vault/edit/
- /vault/extensions/
- /vault/factory/
- /vault/functions/
- /vault/images/
- /vault/import/
- /vault/install/
- /vault/plugins/
- /vault/tab/
- /vault/tools/
- /vault/wiki/
- /vault/admin.php
- /vault/functions.php
- /vault/plugins.php
- /vault/wiki.php
- /showwiki_proxy.php
- Go to AdminCP > VaultWiki 4 > Admin Panel > Permissions > Usergroups
- Make sure that the base permissions for all groups are what you want. There are a lot of new permissions, not all were mapped, and those that were might not be to your liking.
- Next to each Usergroup, click the key icon, which will show custom permissions for that group in other parts of the wiki.
- Review the custom permissions and delete the sets you don't need. A lot of these were created automatically by vBulletin if you ever used the option to "Base on existing usergroup" when you created a new group.
- In the sets you do need, pay close attention to who can and can't use HTML. You don't want to accidentally let the wrong people execute Javascript on your site. To be on the safe side, never set HTML-related permissions to "Not Set." When in doubt, choose "No."
- Admin Panel > Permissions > Moderators, Access Masks. As above, make sure the permissions are all okay.
- Admin Panel > Settings > Wiki Config > Wiki URL Format. If you are using anything other than the first option, then you need to make changes to your .htaccess file or other site config.
- In most cases, simply changing references to "showwiki_proxy.php" to "wiki_index.php" should be sufficient.
- If you had translated custom paths, set up 301 permanent redirects to the untranslated paths now.
- You will also need to add rules to rewrite /yui-combo. In .htaccess, this would be:
In nginx.conf, this is what we have:Code:RewriteRule ^yui-combo/([^/]+)/(.+)$ yui_loader.php?v=$1&f=$2 [L,QSA]
Code:location ~ ^/yui-combo/ { rewrite ^/yui-combo/([^/]+)/(.+)$ /yui_loader.php?v=$1&f=$2 last; }- If you are changing to the third option, and especially if you have vBSEO installed, then please contact support for a review of your settings and your server config for more information on how to proceed.
- You should now be able to view your wiki. Make sure nothing looks horribly wrong.
- If the sidebar seems empty, go to Admin Panel > Contents > Sidebar Blocks, and make minor changes to the ones you want. This will rebuild the cache.
- You will need to rebuild vBulletin's Activity Stream so that it shows existing wiki pages. In the AdminCP, go to Maintenance > General Update Tools, click "Rebuild Activity Stream."
Over Time
When you are satisfied with the upgrade, which should ideally be some time after VaultWiki 4 is declared stable, you should begin cleanup:
- In AdminCP > Forums & Moderators > Forum Manager, delete all wiki forums.