Blog & News

Due to its structure, upgrading mojoPortal is quite simple. The short story is you backup your site and database, download the new version, copy the files to your server, open the setup page and you're done. There are a few areas where one might start over thinking the process and make it harder than it really is so we decided we would write this guide to help quell the desire to make it difficult.

The Canon

The process for upgrading mojoPortal is no different if you are upgrading from a really old version or a relatively new version. mojoPortal doesn't have "minor" updates or "major" upgrades. The terms update and upgrade can be used interchangeably when referring to mojoPortal. Version numbers don't mean much, version 2.4.0.0 didn't necessarily contain any more new features or bug fixes than 2.3.7.2. The version numbers increase by 0.0.0.1 each time a database change or a set of database changes is needed. There are never "upgrade" or "update" packages released by mojoPortal. All releases packages contain a full installation which if copied to an existing site will upgrade the site. If you do not backup your site and database before upgrading, you are not being responsible.

Process Overview

1. Take the Site Offline
2. Backup the Site Files and Database
3. Prepare the web.config File
4. Copy New Files to the Site
5. Bring the Site Online
6. Run the Setup Page
7. Make Skin Changes if Needed

Take the Site Offline

You want to do this prior to backing up the site because once the site is offline, no one can make any changes to it. If you were to backup the site before taking it offline, someone could make a change which is not backed up.

To take the site offline, add an "App_Offline.htm" file to the root of the site. The root of the site is the same location where the web.config file resides. You can download an example App_Offline.htm here.

Backing up

There are many, many ways to backup files and databases. We will cover two methods for backing up files and two methods for backing up databases (one for MSSQL and one for MySQL).

Backing up Files When You Have Access to the Server's Desktop

Use this method if you have access to the servers desktop. If you don't have access to the servers desktop, use the FTP method.

In general, you will want to browse to the location of your site files. If you do not know what this is, you should contact your server admin or, if you are familiar with IIS, check the physical path for the site in IIS. Once you have located the site files, select all of them and create a zip file of them. We use 7-Zip but you can use whatever you like.

Backing up Files with FTP

Download a good FTP client which provides verbose logging and an easy way to retry operations which may have failed. We use FileZilla and recommend it above any other FTP client.

Open your FTP client and connect to your server. Download all of the files in your site to a directory on your computer. Check the FTP Client's log for any failures and re-download any files which did not download properly.

Backing up MSSQL Database in SQL Server Management Studio

Use this method if you have access to the database using SQL Server Management Studio (SSMS). Some hosting providers provide this access but the more security minded hosting providers (like i7MEDIA) do not. If you cannot access the database with SSMS, use your hosting providers control panel tools to back up your database. If you are an i7MEDIA customer, follow the instructions in our "Backing up and Restoring SQL Server Databases" knowledge base article.

Create the Backup

1. Open SSMS and connect to the database server hosting the database.
2. Right-click the database in the Object Explorer of SSMS and then select Tasks > Back Up. For further instructions, read the "Create a Full Database Backup" article on the MSDN website.

Backing up MySQL Database using MySQL Workbench

Use this method if you have access to the database using MySQL Workbench. Some hosting providers provide this access but the more security minded hosting providers (like i7MEDIA) do not. If you cannot access the database with MySQL Workbench, use your hosting providers control panel tools to back up your database. Many hosting providers do provide access to a tool called PHPMyAdmin which you can use to back up your database as well. If you are an i7MEDIA customer, follow the instructions in our "Backing up and Restoring MySQL Server Databases" knowledgebase article.

Create the Backup

1. Open MySQL Workbench and connect to the database server hosting the database.
2. Select "Data Export" under "Management" in the Navigator.
3. Select the database in the "Object Selection" panel.
4. Select your desired options in the Options section and click the "Start Export" button. Note: do not select the "Skip table data" option because you will not end up with any of your site data if you do select this option.

Prepare the web.config File

You should use the web.config file which comes with the mojoPortal release. This cannot be stressed enough because trying to compare every line of your old web.config file and the new one will take a long time and you may miss something. Nearly all of the settings you might change should be done in the user.config file anyway so you shouldn't have many changes to the web.config file in the first place. A few exceptions to this rule are listed below:

machineKey

The machineKey is used for encryption and decryption of authentication cookie data and view-state data. In mojoPortal it is also used for encryption and decryption of stored passwords if the Password Storage option is set to "Encrypted." You should copy this from your previous web.config file to the new web.config file. Read our "Separating Sections From the mojoPortal web.config File" article if you have a lot of sites and don't want to modify the new web.config for each of them.

Keys Related to Large File Uploads

The httpRuntime and requestFiltering elements in the web.config help with the support of large file uploads. If you have made changes to these elements, you will need to copy those changes to the new web.config file. Read the Supporting Large File Uploads article in the mojoPortal documentation for more information on this topic.

Keys Related to Error Pages

The configuration of custom and http error pages for a website hosted in IIS is saved in the web.config file. If you have changed these settings from the default values, you'll need to copy them over to the new web.config file. The customErrors element contains the settings for handling .net related errors and the httpErrors element contains the settings for handling http errors (e.g., 404). Tip: take a look at our article "Pretifying the mojoPortal Error Page" for information on how to modify the .net error page.

If you have several items which cannot go in the user.config file, you should keep them saved in some kind of notes file with the site. For best security, save your notes file with a .config extension to prevent it from being download via the web.

Note: this is an upgrade, not a new install so you should not copy create a new user.config file.

Copy New Files to the Site

If you have access to the servers desktop you can simply copy the files from the release (with changes made to the web.config) to the location of your site files in the order listed below. When prompted to with the option merge existing folders or not, select "yes." When prompted to "Copy and Replace" for existing files or "Don't copy," check the "Do this for all conflicts" checkbox and then click the "Copy and Replace" option.

If you are accessing the site with FTP, again be sure you are using a good FTP client. Using the FTP client, upload all of the files in the order listed below. When prompted to overwrite existing files, choose whichever option overwrites the existing files.

Order to Copy or Upload New Files/Folders

1. Setup folder
2. ClientScript folder
3. Data folder
4. All other files and folders

Bring the Site Online

The site was taken offline by adding the App_Offline.htm file to the root of the site. To bring the site back online, all you need to do is rename or move the file. We generally customize our App_Offline.htm files with customer logos so we simply rename the file to App_Offline.config instead of moving it elsewhere.

Run the Setup Page

The setup page runs all of the database scripts for all of the features which have database changes. It also processes all of the feature configuration files which control what settings you see on the settings page for module instances.

To run the setup page, open a web browser and go to http://www.yourwebsite.url/Setup/Default.aspx. Once all of the scripts run, you will see a summary at the bottom of the page along with a link to the site.

If you see any errors, you will need to address them. Generally, you shouldn't see any errors but we have compiled a short list of the most common errors.

Setup is disabled. To continue, please set DisableSetup to false in Web.config.

This is showing up because the DisableSetup key in the web.config or user.config file has been set to true. If you were logged in to the site prior to upgrading, you will not see this error. To get around this, open the user.config file and change the setting to false. Next, open the web.config file and add a space to the bottom of the file. Finally, reload the setup page.

The system cannot connect to the MSSQL database. Please check your connection string.

The Connection String key in the user.config file is not correct. This error is always accompanied by more detailed information to help you troubleshoot the problem. If the database server can be accessed, it will state something to the effect of "...error occurred while establishing a connection..." If the database name, username or password is incorrect, it will state something to the effect of "the login failed."

Make Skin Changes if Needed

The skins in the mojoPortal release packages are not copied over the skins used by sites (located in \Data\Sites\[sitenum]\skins). The skins located \Data\Skins are updated or appended with the updated or new files from the release package. If you are using a skin which came with mojoPortal and have not modified it, you can copy it from \Data\Skins to \Data\Sites\[sitenum]\skins.

If you are using a custom skin or you have modified a packaged skin, you should check the "Important Skin Changes" article in the mojoPortal Documentation for details on any changes you need to make to your skin to support the new release. You will want to check the details of every version between your old version and the new version you are installing. This is rather easy as the changes are listed in descending order in the article and there aren't very many.

Summary

See, it's rather simple. You don't need to worry about database scripts, different methods for minor or major versions, lots of file merging or anything like that. Really, all you need to do is create a backup and copy over the new files.

If you run into problems, check out the mojoPortal Forums. Do a search for your issue before posting because someone else may have already reported the problem and resolution has been provided by the community.

Want someone else to do it?

If you would rather have someone else handle upgrades for you, check out our Upgrade Service.

Want to learn more about mojoPortal?

If you enjoyed this guide and would like to learn more about mojoPortal, check out our Training Classes.