As of version 4.2.11, Sitellite features a new upgrade utility that makes upgrading a little easier, more flexible, and more reliable. The process is still primarily manual, but this extended guide should help make that easier as well.

Note: Always back up your existing website first!

Introduction

In this guide we're going to install the upgrade in a separate location, then move it over once the upgrade process has been completed and the new site has been tested. This is important because it avoids attempting to upgrade a live website, which is bad practice. At the very least your visitors may see the site in an inconsistent state, and worst case something goes wrong and your visitors see a broken website until you've restored the backup (you didn't skip step one, did you?).

Because of this, upgrading will require a separate website root on the same server as your website, as well as a separate temporary MySQL database. We usually recommend using a subdomain (ie. upgrade.yourwebsite.com) for the temporary upgrade spot.

Note: To find the current version of Sitellite, see the file inc/conf/version.php or go to Control Panel > Tools > Upgrade Utility.

Step 1. Take Stock

Take stock of any settings changes and customizations you have made and create a list of all of these. Be sure to include the names of the files changed, including their full path from the website root folder. These will duplicated to the upgraded site in step 3. An example list would be:

inc/app/news/conf/properties.php - News section configurations
inc/app/myapp - Custom code for this site
inc/app/siteevent/conf/properties.php - Event listings configuratiosn

Places to look for custom settings and other customizations include:

1. inc/app - Custom apps may reside here (ie. "myapp")
2. inc/app/*/conf/properties.php - Application-specific settings
3. inc/app/*/data - Data specific to an app (not all apps have this, but some do including SiteBanner, SiteConnector, and SiteSearch)
4. inc/app/*/lang - Translation files for individual apps
5. inc/app/cms/conf/collections - Custom collections (ie. content types)
6. inc/app/cms/conf/services - Custom workflow services
7. inc/app/cms/data - Version history for Web Files collection
8. inc/conf - Global configurations
9. inc/data - Web Files data storage
10. inc/html - Custom template sets
11. inc/lang - Global translation files
12. inc/sessions - Session/authentication configurations

Note: This step is something you'll only have to do the first time (or something you can do as part of the process of building your initial site), and can be reused with minor updates over time as your site is extended or modified. It also serves as useful documentation for your development team.

It's also a good idea at this time to read through the change log and make note of any changes that may affect your website based on your system configuration (Apache/MySQL/PHP versions, etc.) and which apps your website makes use of. This is found in the file install/changes.txt or through the Control Panel under Tools > Upgrade Utility.

Step 2. Install the Upgrade

Install the new download of Sitellite as a secondary site. Sitellite upgrades come as a full copy, not as a patch for your existing version. Only the database and your data/customizations are preserved from your existing installation, so nothing on the site is lost but you can't simply "drop in" the upgrade -- you need to install it in a secondary location.

Do not simply replace the old site with the new installation, this will overwrite existing data. See Sitellite installation instructions for this. Please note that you will need a secondary temporary web space and an additional temporary MySQL database for this step. Most modern website hosts provide sufficient space and features that this should not be an issue.

Step 3. Copy Settings/Customizations

Once you have your new Sitellite installation of the latest release up and running, now you will need to copy your existing website settings over, including templates and database settings, to the new site. These were collected in step 1.

For example:

cp -R /path/to/old_site/inc/data/* /path/to/new_site/inc/data/
cp -R /path/to/old_site/inc/app/cms/data/*
  /path/to/new_site/inc/app/cms/data/
cp -R /path/to/old_site/inc/app/cms/conf/collections/*
  /path/to/new_site/inc/app/cms/conf/collections/
cp -R /path/to/old_site/inc/app/cms/conf/services/*
  /path/to/new_site/inc/app/cms/conf/services/
cp -R /path/to/old_site/inc/html/my_template_set
  /path/to/new_site/inc/html/
etc.

For individual files such as your global configurations and properties.php files from individual apps, you should compare them to the new ones before simply copying the old ones over, since new properties may have been added to these files between releases.

For files modified from the original source code, you may need to compare the two versions of these files using a utility such as diff which will highlight the differences and allow you to merge them to produce a new current version with the upgrade modifications as well as your own. For more info about this, please see below under "Patching Modified Files".

Step 4. Upgrade Utility

Now log into the new Sitellite website and go to Control Panel > Tools > Upgrade Utility. From here, click on the "Apply the 4.x.x upgrades" link. This will perform any necessary database and other automated updates.

Note: For releases before 4.2.11, please see the note at the bottom of this article

Step 5. Testing

You should now have a fully working copy of your website running on this new copy of Sitellite. Make sure you test everything to make sure it works. When you've finished testing it, you should be safe to replace your existing website with this new one.

Some places to be sure to verify things are correct include:

• All public-facing applications and pages
• Control Panel > Admin > Site Settings
• Control Panel > Admin > Workflow Services
• Admin login and member login facilities
• Basic editing functions

Patching Modified Files

If you modified an original source file, your best bet is to create a patch file from the two web sites to know what is different between them. For example:

diff -c /path/to/old_site/some_file.php /path/to/new_site/some_file.php > diff.txt

Review the newly created diff.txt file and make sure there are no conflicts. If all is well, you can apply the patches described in that file as follows:

patch -i diff.txt

To do the same thing for an entire folder, use the following commands:

diff -cr /path/to/old_site/some_folder /path/to/new_site/some_folder > diff.txt

This patch can then be applied like this:

cd /path/to/old_site/some_folder
patch -i ~/diff.txt

For more info on comparing and patching files usind diff and patch, see A Short Introduction to GNU Diff and Patch.

A Note About Previous Releases

In previous versions of Sitellite, instead of step 4 you would have manually applied the appropriate database updates and other updates for your Sitellite version from the "upgrade" folder. Database updates could be applied with the following command:

mysql -p -u USER DBNAME < upgrade/4.2.6-4.2.7.sql
(enter password)

Note that if you were upgrading from a much earlier release than the previous current one, you would apply each database update sequentially between the original version and the new one.