pegasus

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, you cannot yet take advantage of this system.

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.

Preparing for Upgrade

The following steps should be taken BEFORE uploading any files to your server:

1. In AdminCP > Settings > Options > VaultWiki: Server Settings, set "Turn on the Wiki?" to No.
2. 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.
3. 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.
4. 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.
5. In AdminCP > Plugins & Products > Product Manager, disable VaultWiki.
6. 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.

1. As usual, log into your account on vaultwiki.org and proceed to the Members tab.
2. 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 Beta 5), and make sure you choose to download the whole package.
3. 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.
4. 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.
5. Navigate to yoursite/vault/install/index.php
6. Click "Install." 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.
7. 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... you may notice that there are now 2 copies of VaultWiki installed on your forum: version 3 and version 4. Do NOT panic. This is intentional...

Importing Your VaultWiki 3 Data

None of your old data was actually migrated yet. It's still safe and sound under the old VaultWiki product. In order to migrate your old data, you will use VaultWiki 4's import system.

1. In the VaultWiki Admin Panel, go to Settings > Site Config, and update these settings to match your current wiki settings as closely as possible.
2. Go to Content > Import/Export.
3. For Source Format, select "VaultWiki 3" and click Import.
4. This will open the 1-click importer. Click Import again to start the process.
5. When the process is complete, you can continue with the steps below.

After Importing

There's still quite a bit to do. The importer 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.

1. Go to AdminCP > VaultWiki 4 > Admin Panel > Permissions > Usergroups
   
   1. 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.
   2. Next to each Usergroup, click the key icon, which will show custom permissions for that group in other parts of the wiki.
   3. 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.
   4. 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."
   
   
2. Admin Panel > Permissions > Moderators, Access Masks. As above, make sure the permissions are all okay.
3. 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.
   
   1. In most cases, simply changing references to "showwiki_proxy.php" to "wiki_index.php" should be sufficient.
   2. If you had translated custom paths, set up 301 permanent redirects to the untranslated paths now.
   3. 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.
   
   
4. You should now be able to view your wiki. Make sure nothing looks horribly wrong. If the data wasn't imported properly, please report the errors to our support.
5. If the import looks to have been successful and the data is correct, you can uninstall the old VaultWiki 3 product by following these steps:
   
   • To avoid removing shared data, first download the ZIP attached to this post.
   • Replace the file vault/tools/uninstall.php with the file in the ZIP (updated 11/21/2015).
   • Visit AdminCP > Plugins & Products > Manage Products, and select Uninstall from the Controls for VaultWiki. WARNING: Make sure you are only removing version 3! It's likely version 4 will be right above or below it in the product list. When the confirmation appears, the productid you want to remove is "ces_nwsp_spec."
   • Once VaultWiki 3 is removed, we can continue configuring VaultWiki 4.
6. 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.
7. 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."
   
8. 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 now that VaultWiki 3 is removed, 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

Over Time

You should begin cleanup:

1. In AdminCP > Forums & Moderators > Forum Manager, delete all old wiki forums.