Upgrading¶

Check minimum requirements¶

Please refer to the Minimum requirements page to make sure that your system meets all the requirements. This is especially important if you are going to be upgrading from an older version of ICA-AtoM (1.1 - 1.3.1 or later), as there will be some new dependencies that we will install as part of the upgrade process.

Read the release notes¶

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

As a major release with hundreds of issue tickets closed, made public during a time when AtoM is in the process of rewriting its documentation and migrating wiki content, the AtoM 2.0.0 release notes were made in a more general form in our User forum, here.

In the future, we will update these instructions with a consistent place on our new wiki (coming soon), where you can always find release notes for the latest version of AtoM, as well as those from previous releases.

Install the latest version of AtoM¶

Follow the instructions available in our documentation on Installation - our most comprehensive installation notes are included in the Linux section, with additional information for different operating systems and server configurations.

Copy your old data¶

At this point, you should have an 2.4 functional installation using a fresh database. Now we are going to copy the contents of the old uploads and downloads directories, 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. Using the command-line, enter the following command:

$ rsync -av /var/www/icaatom_old/uploads/ /usr/share/nginx/atom/uploads/

Where icaatom_old is the name of your old installation. The path included for the new installation in this example (/usr/share/nginx/atom) is the path we recommend in our installation documentation.

Alternatively, you can just use cp:

$ cp -r /var/www/icaatom_old/uploads/ /usr/share/nginx/atom/uploads/

We’re going to want to do the same with the downloads directory as well - this is where reports, cached xml, and downloads created by the job scheduler (such as clipboard exports) are kept.

$ rsync -av /var/www/icaatom_old/downloads/ /usr/share/nginx/atom/downloads/

rm -f /usr/share/nginx/atom/downloads/jobs/*

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

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

3. Drop and re-create the new AtoM database to remove any unnecessary tables and columns.

$ mysql -u username -p -e 'drop database new_database; create database
new_database character set utf8 collate utf8_unicode_ci;'

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

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

Run the upgrade task¶

This is perhaps the most critical step in the upgrade process. If you encounter any errors, please consult our User Forum, or if you don’t find a solution, feel free to post a question there yourself. We will also be trying to add to our FAQ as we receive feedback, to help users troubleshoot any upgrading issues encountered.

First, change the current directory:

$ cd /usr/share/nginx/atom

Now, run the upgrade-sql task:

$ php symfony tools:upgrade-sql

Migrate translations¶

Regenerate the digital object reference and thumbnail images (optional)¶

If you are upgrading from version 1.3.1 or earlier, you may want to regenerate the digital object reference and thumbnail images. The thumbnail size was smaller in 1.x, so those images will often appear fuzzy in the redesigned digital object browse. A directory naming convention has also been added to make the location of the master digital object more secure.

First, make sure you have not changed the directory (/usr/share/nginx/atom).

Now, run the regen-derivatives task:

php symfony digitalobject:regen-derivatives

For more information on this task and its available options, see: Regenerating derivatives.

Rebuild search index and clear cache¶

To make all these changes take effect, you will need to re-index the files you’ve imported into your database, and clear the application cache.

First, rebuild the search index:

php symfony search:populate

For more information and options on this task, see: Populate search index.

Then, clear your cache to remove any out-of-date data from the application:

$ php symfony cc

See Clear cache for more detailed instructions.

Restart services¶

To ensure everything works correctly, you must restart your services after upgrading, including PHP-FPM, Memcached (if you’re using it as cache engine), and the atom-workers managed by the job scheduler.

To restart PHP-FPM:

Ubuntu 14.04:

sudo service php5-fpm restart

Ubuntu 16.04:

sudo systemctl restart php7.0-fpm

Optionally, to restart Memcached:

Ubuntu 14.04:

sudo service memcached restart

Ubuntu 16.04:

sudo systemctl restart memcached

To restart the atom-workers:

Ubuntu 14.04:

sudo restart atom-worker # Restarts the workers
sudo status atom-worker  # Obtain current running status

Ubuntu 16.04:

sudo systemctl restart atom-worker  # Restarts the workers
sudo systemctl status atom-worker   # Obtains current status

Set site base URL¶

One final step is to set your site’s base URL. This URL is used in XML exports to formulate absolute URLs referring to resources.

To set the site base URL:

1. Click on the Admin menu in the main menu located in the header bar and select Settings.
2. Click on or scroll down to Site information. Enter your site’s base URL into the site base URL field. If your domain is “townarchives.org”, for example, your base URL would normally be “http://townarchives.org”.

Upgrading with a custom theme plugin¶

If you have developed a custom theme plugin for your application (for more information, see Create a custom theme), you may need to perform an additional step following an upgrade to ensure that all pages are styled correctly.

Specifically, The Job details page may not appear properly styled in a custom theme without an additional step. To ensure your Jobs pages properly inherit the base Dominion theming, you will need to add a call to import the jobs.less CSS file to your theme plugin’s main.less file. If you have followed our recommendations for creating a theme plugin, then you should find the main.less file for your plugin in plugins/yourThemePluginName/css/main.less. Here is an example of where you need to add a line in the ArchivesCanada theme plugin:

• https://github.com/artefactual/atom/blob/HEAD/plugins/arArchivesCanadaPlugin/css/main.less#L78

The line you will need to add is to import the base Jobs CSS, like so:

@import "../../arDominionPlugin/css/less/jobs.less"

After adding the line, you should rebuild the CSS for the plugin, using the make command. Here is an example of rebuilding the CSS for the ArchivesCanada theme - you can swap in the name of your plugin:

make -C plugins/arArchivesCanadaPlugin

You will also want to clear the application cache, and restart PHP-FPM.

To clear the application cache:

php symfony cc

For more information, see: Clear cache.

To restart PHP-FPM on Ubuntu 14.04:

sudo service php5-fpm restart

To restart PHP-FPM on Ubuntu 16.04:

sudo systemctl restart php7.0-fpm

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.

Back to top