Sitellite Server Administration

Chapter 5: Backups and Upgrades

Components to Back Up

The main components to consider when backing up a Sitellite installation are the database and the files. So packaging up a backup requires first that you export the MySQL database to a file that can be backed up with the rest of the files.

Simple Backup

A backup solution can be as simple as the following shell script:

cd /PATH/TO/SITELLITE
mysqldump --password='PASS' -u USER DBNAME > backup.sql
tar -cf backup.tar .htaccess *
gzip backup.tar
cp backup.tar.gz /PATH/TO/BACKUPS
rm -Rf backup.sql backup.tar.gz

If you save that script to ~/bin/backup.sh and set the permissions on the ~/bin folder and the backup script to 0700, you could run it via cron with the following entry:

0 4 * * * /home/USER/bin/backup.sh

Backups with RSync and SSH

My preferred backup method for our sites is to use rsync and SSH to perform the backups. Backing up a gzipped file is okay because the resulting file is stored efficiently, but rsync only backs up the changes made to files since the last backup, so it's better on bandwidth which can add up over time. In this example, rsync is also tunnelled through SSH so the data is sent securely.

To setup rsync securely, you first have to generate and exchange SSH keys between the live and backup servers.

To generate an SSH key on the live machine (not the backup server), enter the following command. When it asks you for a passphrase, just hit enter and leave it blank.

ssh-keygen -t dsa -b 1024 -f /home/USER/rsync-key

Now that you have the key, you need to share it with the backup server. To transfer the public key to the backup server, use the following command:

scp /home/USER/rsync-key.pub remoteuser@backupserver:/home/remoteuser/

Next you'll have to log into the backup server via SSH and install the public key. The following series of commands will take care of that.

if [ ! -d .ssh ]; then mkdir .ssh ; chmod 700 .ssh ; fi
mv rsync-key.pub .ssh/
cd .ssh/
if [ ! -f authorized_keys ]; then touch authorized_keys ; fi
chmod 600 authorized_keys
cat rsync-key.pub >> authorized_keys

Next, as an added security step, open the file .ssh/authorized_keys and find the start of the key you just added to the file. The line should start with "ssh-dss" and you want to change this to include the IP address of the live server:

from="1.2.3.4" ssh-dss ...

You should now be able to SSH into the backup server from the live one without a password by using your key.

ssh -i /home/USER/rsync-key remoteuser@backupserver

If this works, you should be all set to install an rsync-based backup script into ~/bin/backup.sh. The following is an example script. The values at the top need to be modified with the actual info for your site.

#!/bin/sh

# the path to the sitellite installation
SITE="/PATH/TO/SITELLITE"

# the IP address of the backup server
RMACHINE=1.2.3.4

# the username on the backup server
RUSER=USER

# your rsync SSH key on the live server
RKEY=/home/USER/rsync-key

# the target folder on the backup server
RTARGET="/PATH/TO/BACKUPS"

# edit the USER, PASS and DBNAME here as well
mysqldump -A -f -u USER --password="PASS" DBNAME > $SITE/.htbackup.sql
gzip -f $SITE/.htbackup.sql

if [ ! -f $RKEY ]; then
  echo "Couldn't find ssh keyfile!"
  echo "Exiting..."
  exit 2
fi

if ! ssh -i $RKEY $RUSER@$RMACHINE "test -x $RTARGET"; then
  echo "Target directory on remote machine doesn't exist or bad permissions."
  echo "Exiting..."
  exit 2
fi

if ! ssh -i $RKEY $RUSER@$RMACHINE "test -d $RTARGET/$SOURCE"; then
  ssh -i $RKEY $RUSER@$RMACHINE "mkdir -p $RTARGET/$SOURCE"
fi

rsync -a --delete -e "ssh -i $RKEY" $SOURCE/ $RUSER@$RMACHINE:$RTARGET/$SOURCE/

rm $SITE/.htbackup.sql

exit 0

Using the same cron entry as before, your site should now automatically backup via rsync over SSH nightly at 4am.

Upgrading Sitellite

First, back up your site. Never attempt to perform an upgrade without first backing everything up. It's also a good idea not to perform the upgrade on a live site directly, but rather to set up a duplicate test site and use that to perform the upgrade, in case something goes wrong.

Upgrading Sitellite is a mostly manual process, but first, you'll need to check which version of Sitellite you're running by going to the Control Panel > Tools > Upgrade Utility. The current version is printed on the main screen of the upgrade utility. You'll need to remember this for later, so it may be good to write it down.

In this lesson, 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. 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.

Taking 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 configurations

Places to look for custom settings and other customizations include:

inc/app - Custom apps may reside here (ie. "myapp")
inc/app/*/conf/properties.php - Application-specific settings
inc/app/*/data - Data specific to an app (not all apps have this, but some do including SiteBanner, SiteConnector, and SiteSearch)
inc/app/*/lang - Translation files for individual apps
inc/app/cms/conf/collections - Custom collections (ie. content types)
inc/app/cms/conf/services - Custom workflow services
inc/app/cms/data - Version history for Web Files collection
inc/conf - Global configurations
inc/data - Web Files data storage
inc/html - Custom template sets
inc/lang - Global translation files
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.

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.

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".

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.

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 /old_site/some_file.php /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 /old_site /new_site > diff.txt

This patch can then be applied like this:

cd /old_site
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.

Comments

You must be logged in and registered for this course to comment.

Username:
Password:
	Forgot your password?

Member Login