Upgrading an ACS Installation

This document will walk you through upgrading ACS from one major version to the next. If you need to upgrade across several major versions, take them one at a time. If you haven’t kept up-to-date for a really long time, it may be better to start afresh and invent a way to move your old data into the new system. See the <a href=”http://www.arsdigita.com/doc/upgrading”>other upgrading document for how to do that.

The process being outlined here involves shutting the site down for an hour or two while the upgrade takes place. We’ll update the document later to include how to do it without taking the live site down.

The steps are:

1. Stop you webserver.
   
   
2. Download and untar the new version.
   
   
3. Import the new files and resolve conflicts.
   
   
4. Back up your database.
   
   
5. Figure out what minor version your database is at.
   
   
6. Upgrade the database.
   
   
7. Do any version-specific upgrade tasks.
   
   
8. Start the webserver.
   
   
9. Test.
   
   

1. Stop Your Webserver

Turn off the line for your webservice in /etc/inittab. Remember that you can’t comment out lines in inittab on Solaris. Instead, change respawn to off. Then type init q on the command line to have the server process killed.

2 and 3. Download, Untar, Import, Resolving Conflicts

This is already described in detail in <a href=”http://www.arsdigita.com/doc/runbook/project-management#upgrade”>the project management document in the ACS Runbook.

4. Back Up Your Database

You can do this with

exp <i>yourservice</i>/<i>password</i> owner=<i>yourservice</i> file=<i>yourservice</i>.dmp consistent=y

Make sure it completes without hickups.

5. Figure Out Your Minor Version

If you’re in doubt, fire up SQLPlus, open the first minor upgrade script for your major version (e.g. upgrade-3.2-3.2.1.sql and check if the first few changes from that file have been done with describe <i>objectname</i>. Continue till you find something that hasn’t been done, and here’s where you should start.

6. Upgrade The Database

Programmers make mistakes. We haven’t been good enough at testing in the past. Therefore, we urge you to interactively run the upgrade scripts, rather than run the automatically. That way you’ll know what worked and what didn’t and resolve the problems by hand. This is especially a good idea, if you’ve made custom development on top of the toolkit.

The most convenient way to do it is to fire up SQL

Plus in a shell buffer in Emacs (M-x rename-buffer to sqlplus), then open the upgrade script in another buffer (you probably already have it open from step 5).

Copy the stuff from the upgrade-script buffer to the SQL*Plus buffer bit by bit and make sure there aren’t any problems. The upgrade scripts are divided into blocks concerning each their part. Experience shows that if the first few statements in a block succeed, you can be reasonably safe taking larger chunks from within that block, but go by your intuition.

7. Version-specific Upgrade Tasks

Some versions have specific things you need to do. For example, ACS 3.3 requires you to deleted some files in special places. Check the release notes for these.

8. Start the Web Server

Fire up another shell in Emacs, and do a

tail -f /home/aol30/log/<i>yourserver</i>-error.log

Change /etc/inittab back, so it says respawn again, and init q. Check that the webserver is running. Search for “Error” or other suspicious-looking messages in the error log.

9. Test

Surf around your website, to make sure that everything worked okay.