Upgrading

Main Page > Administrator manual > Upgrading

Preliminary considerations

This guide explains how to upgrade from Release 1.1 or 1.2 to Release 1.3 or newer. If your scenario is different, please refer to the Qubit upgrading documentation. However, we strongly recommend our users to install the latest release because it is safer, faster, more stable and includes all kind of new features and enhancements.

While we have tried to make this document usable by readers with a broad range of technical knowledge, it may be too complex if you have no previous experience with installing web applications or using the Linux command line.

Additionally, consider disabling your web site during the upgrade. Redirect your users to a "Down for maintenance" page temporary using your web server redirection capabilities. The following link explains how to do that using Apache and mod_rewrite: http://davidwalsh.name/htaccess-maintenance-page-redirect.

Check requirements

Please refer to the Minimum requirements page to make sure that your system meets all the requirements.

Read the release notes

This is the opportunity to find out what has been changed in the new release, there are new features, enhancements and bug fixes that may be of interest to you and your organization.

Back up existing files and the database

Before proceeding with the upgrade, please make a full backup of all your data following our instructions: Data backup.

Dumping your data must be done before updating to the latest version of the application.

Unpack the new files

If you wish to install to the same directory as your previous version you must remove the old installation directory first. Moving the existing directory, rather than deleting it, preserves any digital objects, custom files or translations for transfer to the new version of the application. For example:

$ mv /var/www/icaatom /var/www/icaatom_old

Download the latest ICA-AtoM tarball and extract it in a new directory of your web root. For example, to extract the icaatom-1.3.0.tgz tarball to the /var/www/icaatom-1.3.0 directory, type:

$ tar xvzf icaatom-1.3.0.tgz -C /var/www

Now, please set the file and directory permissions as explained.

Run the installer

See Installation for instructions on running the web-based application installer.

Remember to create a new database for this installation, you don't want to use the old one because the installer will erase all the data.

Copy the data

At this point, you should have an ICA-AtoM functional installation using the new fresh database. Now we are going to copy the contents of the old uploads directory as well as the database:

1. rsync is a robust directory sync solution that we can use to copy the contents of your old uploads directory to the new one, even when both directories are in the same machine:

   $ rsync -av /var/www/icaatom_old/uploads /var/www/icaatom-1.3.0/uploads

   Alternatively, you can just use cp:

   $ cp -r /var/www/icaatom_old/uploads /var/www/icaatom-1.3.0/uploads

2. Dump the contents of your old database to a temporary file:

   $ mysqldump -u username -p old_database > /tmp/database.sql

3. Now, load the contents into the new database:

   $ mysql -u username -p new_database < /tmp/database.sql

Run the upgrade task

Change the current directory:

$ cd /var/www/icaatom-1.3.0

Now, run the upgrade-sql task:

$ php symfony tools:upgrade-sql

This is the most critical step in this upgrade guide. If you get an error, please read our FAQ below to troubleshoot any problems.

Migrate translations

If you have done any custom translations of the user interface, they will be stored in the apps/qubit/i18n directory. Copy them from your old application directory to the new:

$ cp -r /var/www/icaatom_old/apps/qubit/i18n /var/www/icaatom-1.3.0/apps/qubit/i18n

Your translated metadata (archival descriptions, authority records, archival institutions, etc.) is stored in the database, and will be restored from your data dump.

Rebuild search index

Due to data changes during the upgrade process, you will need to rebuild the search index after upgrading:

$ php symfony search:populate QubitSearch

Clear cache

Clear your cache to remove any out-of-date data from the application,

$ php symfony cc

See Clear cache for more detailed instructions.

Start using the software!

Congratulations! If you are reading this, it means that you have upgraded your data successfully. Now please check that everything is working fine.

Before you put your site in production again, please take a look at your data and check that everything looks good and correct. The upgrading system changed dramatically since Release 1.2. We have tested it intensively against more than 20 different sites, but still we think that double checking is always necessary. Let us know if you find any problem!

Frequently asked questions

Why do I get a "Class QubitActor contains 4 abstract methods" error?

If you are running a command line (CLI) task (e.g. rebuild the search index) and you get an error like

Fatal error: Class QubitActor contains 4 abstract methods and must therefore be declared abstract or implement the remaining methods ...

You need to clear the cache two times in a row.

$ php symfony cc && php symfony cc

Then re-run your CLI task.

Why do I get a "The task failed while trying to upgrade to..." error?

Something went wrong during the upgrade. The new ICA-AtoM 1.3 upgrade script has been tested again more than 20 different sites but it may fail due to unknown bugs. Please, contact us through the ICA-AtoM Users discussion list.

It is specially important that you send us the error message printed by the upgrade script.

Why do I get a "SQLSTATE[HY000]: General error: 1025 Error on rename of..." error?

This problem has been reported by two users trying to upgrade from Release 1.1 to Release 1.3.
Visit the ticket in our tracker for more details: https://projects.artefactual.com/issues/4970 This problem is going to be fixed in Release 1.3.1.

What should I do if I get an error that isn't described here?

First, please check our main FAQ. Also, try searching the ICA-AtoM Users discussion list for previous posts that may answer your question.

If you can't find any previous posts that are relevant, then please start a new topic on the ICA-AtoM Users discussion list, and be sure to include:

1. A subject line that briefly describes the problem (e.g. "Error when I try to run tools:sql-upgrade")
2. A detailed description of how to reproduce the problem
3. Send us a screenshot of the error, and attach it to your post
4. Which version of PHP are you using?