Prev | Chapter 5. Upgrading | Next

## Upgrading OpenACS

### Upgrading 4.5 or higher to 4.6.3

The required platform for OpenACS 4.6 is the same as 4.5, with the exception of OpenFTS. OpenACS 4.6 and later require OpenFTS 0.3.2 for full text search on PostGreSQL. If you have OpenFTS 0.2, you'll need to upgrade.

If upgrading from 4.2, you need to manually run acs-kernel/sql/postgres/upgrade-4.2-4.5.sql. See Bug #632

- A computer with OpenACS 4.5.

- OpenACS 4.6 tarball or CVS checkout/export.

- Required for Full Text Search on PostgreSQL: OpenFTS 0.3.2

1. Make a Backup. Back up the database and file system (see the section called “Manual backup and recovery”).

2. OPTIONAL: Upgrade OpenFTS. the section called “Upgrading OpenFTS from 0.2 to 0.3.2”

3. Stop the server

       [root root]# svc -d /service/service0

4. Upgrade the file system. the section called “Upgrading the OpenACS files”

5. Start the server

       [root root]# svc -u /service/service0

6. Use APM to upgrade the database.

   1. Browse to the package manager, `http://yourserver/acs-admin/apm`.

   2. Click `Install packages.`

   3. Select the packages you want to install. This should be everything that says `upgrade`, plus any new packages you want. It's safest to upgrade the kernel by itself, and then come back and upgrade the rest of the desired packages in a second pass.

   4. On the next screen, click `Install Packages`

   5. When prompted, restart the server:

          [root root]# restart-aolserver service0

   6. Wait a minute, then browse to the package manager, `http://yourserver/acs-admin/apm`.

   7. Check that the kernel upgrade worked by clicking `All` and making sure that `acs-kernel` version is 5.1.0d1.

7. Rollback. If anything goes wrong, roll back to the backup snapshot.

### Upgrading OpenACS 4.6.3 to 5.0

- Oracle. Not yet documented. It should be possible to upgrade via the APM just as when upgrading to 4.6.3.

- PostGreSQL. You must use PostGreSQL 7.3.x or newer to upgrade OpenACS beyond 4.6.3. See Upgrade PostGreSQL to 7.3; Table 2.2, “Version Compatibility Matrix”

  1. Back up the database and file system.

  2. Upgrade the file system for packages/acs-kernel. the section called “Upgrading the OpenACS files”

  3. Upgrade the kernel manually. (There is a script to do most of the rest: /contrib/misc/upgrade_4.6_to_5.0.sh on HEAD). You'll still have to do a lot of stuff manually, but automated trial and error is much more fun.)

         [root root]# su - service0
         [service0 aolserver]$ cd /var/lib/aolserver/ service0/packages/acs-kernel/sql/postgresql/upgrade

     Manually execute each of the upgrade scripts in sequence, either from within psql or from the command line with commands such as ``psql -f upgrade-4.6.3-4.6.4.sql service0``. Run the scripts in this order (order is tentative, not verified):

         psql -f upgrade-4.6.3-4.6.4.sql service0
         psql -f upgrade-4.6.4-4.6.5.sql service0
         psql -f upgrade-4.6.5-4.6.6.sql service0
         psql -f upgrade-4.7d-4.7.2d.sql service0
         psql -f upgrade-4.7.2d-5.0d.sql service0
         psql -f upgrade-5.0d-5.0d2.sql service0
         psql -f upgrade-5.0d2-5.0d3.sql service0
         psql -f upgrade-5.0d6-5.0d7.sql service0
         psql -f upgrade-5.0d7-5.0d9.sql service0
         psql -f upgrade-5.0d11-5.0d12.sql service0
         psql -f upgrade-5.0.0a4-5.0.0a5.sql service0
         psql -f upgrade-5.0.0b1-5.0.0b2.sql service0
         psql -f upgrade-5.0.0b2-5.0.0b3.sql service0
         psql -f upgrade-5.0.0b3-5.0.0b4.sql service0

  4. Upgrade ACS Service Contracts manually:

         [service0 aolserver]$ cd /var/lib/aolserver/ service0/packages/acs-service-contracts/sql/postgresql/upgrade
         psql -f upgrade-4.7d2-4.7d3.sql service0

  5. Load acs-authentication data model.

         psql -f /var/lib/aolserver/service0/openacs-5/packages/acs-authentication/sql/postgresql/acs-authentication-create.sql service0

  6. Load acs-lang data model.

         psql -f /var/lib/aolserver/service0/packages/acs-lang/sql/postgresql/acs-lang-create.sql service0

  7. (This step may overlap with the two previous steps, but I think it's harmless?) Create a file which will be executed on startup which takes care of a few issues with authentication and internationalization: create service0/tcl/zzz-postload.tcl containing:

         if {![apm_package_installed_p acs-lang]} {
         apm_package_install -enable -mount_path acs-lang [acs_root_dir]/packages/acs-lang/acs-lang.info
         lang::catalog::import -locales [list "en_US"]
         }

         if {![apm_package_installed_p acs-authentication]} {
         apm_package_install -enable [acs_root_dir]/packages/acs-authentication/acs-authentication.info
         apm_parameter_register "UsePasswordWidgetForUsername" \
         "Should we hide what the user types in the username
         field, the way we do with the password field? Set
         this to 1 if you are using sensitive information
         such as social security number for username." \
         acs-kernel 0 number \
         security 1 1
         parameter::set_value -package_id [ad_acs_kernel_id] -parameter UsePasswordWidgetForUsername -value 0
         }

  8. If you can login, visit /acs-admin/apm and upgrade acs-kernel and acs-service-contract and uncheck the data model scripts. Restart. If everything is still working, make another backup of the database.

  9. Upgrade other packages via the APM

  See also these forum posts: Forum OpenACS Development: 4.6.3 upgrade to 5-HEAD: final results, OpenACS 5.0 Upgrade Experiences.

### Upgrading 5.0.0 to 5.0.x

- Upgrading a stock site. If you have no custom code, and your site is not in a CVS repository, upgrade with these steps:

  1. Go to /acs-admin/install/ and click "Upgrade Your System" in "Install from OpenACS Repository"

  2. Select all of the packages you want to upgrade and proceed

  3. After upgrade is complete, restart the server as indicated.

  4. If you are using locales other than en_US, go to acs-lang/admin and "Import all Messages" to load the new translated messages. Your local translations, if any, will take precedence over imported translations.

- Upgrading a Custom or CVS site. If you have no custom code, and your site is not in a CVS repository, upgrade with these steps:

  1. Upgrade the file system for all packages in use. the section called “Upgrading the OpenACS files”

  2. Go to /acs-admin/install/ and click "Upgrade Your System" in "Install from local file system"

  3. Select all of the packages you want to upgrade and proceed

  4. After upgrade is complete, restart the server as indicated.

  5. If you are using locales other than en_US, go to acs-lang/admin and "Import all Messages" to load the new translated messages. Your local translations, if any, will take precedence over imported translations.

Prev | Home | Next
Overview | Up | Upgrading the OpenACS files

View comments on this page at openacs.org