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

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.

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/uploads

   Alternatively, you can just use cp:

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

2. Load the contents of your old database into the new one. There are different ways to do that, for example:

   $ mysqldump -u username -p old_database | mysql -u username -p new_database

Run the upgrade task

Change the current directory:

$ cd /var/www/icaatom

Now, run the upgrade-sql task:

$ php symfony tools:upgrade-sql

This is the most critical step of this guide. If you get an error, please read our FAQ below to answer any question.

Migrate translations

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

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/apps/qubit/i18n

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 /var/www/icaatom/symfony cc

See Clear cache for more detailed instructions.

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 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 cache two times in a row

php symfony cc && php symfony cc

Then re-run your CLI task.

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

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.

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?