Difference between revisions of "Upgrading"

From ICA-AtoM
Jump to navigation Jump to search
(Created page with "== Basic overview == # Check requirements # Read the release notes # Back up existing files and the database # Unpack the new files # Upgrade database == Check requirements ...")
 
 
(78 intermediate revisions by 3 users not shown)
Line 1: Line 1:
== Basic overview ==
+
[[Main Page]] > [[Administrator manual]] > Upgrading
  
# Check requirements
+
== Preliminary considerations ==
# Read the release notes
+
 
# Back up existing files and the database
+
<div class="text-alert">
# Unpack the new files
+
'''This guide explains how to upgrade from [[Release 1.1]] or [[Release 1.2|1.2]] to [[Release 1.3]] or newer.''' If your scenario is different, please refer to the [https://www.qubit-toolkit.org/wiki/Upgrading 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.
# Upgrade database
+
</div>
 +
 
 +
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 ==
 
== Check requirements ==
  
ICA-AtoM 1.3 did not introduce new 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 [https://www.ica-atom.org/doc/Category:Releases 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]].
 +
 
 +
<div class="text-alert">
 +
Dumping your data must be done '''before''' updating to the latest version of the application.
 +
</div>
 +
 
 +
<br />
 +
 
 +
== 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:
 +
<pre>
 +
$ mv /var/www/icaatom /var/www/icaatom_old
 +
</pre>
 +
 
 +
Download the [https://www.ica-atom.org/download.html 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:
 +
<pre>
 +
$ tar xvzf icaatom-1.3.0.tgz -C /var/www
 +
</pre>
 +
 
 +
Now, please [[qubit:Installation_-_Setting_directory_and_file_permissions|set the file and directory permissions]] as explained.
 +
 
 +
== Run the installer ==
 +
 
 +
See [[Installation]] for instructions on running the web-based application installer.
 +
 
 +
<div class="text-alert">
 +
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.
 +
</div>
 +
 
 +
== 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:
 +
 
 +
# 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: <pre>$ rsync -av /var/www/icaatom_old/uploads /var/www/icaatom-1.3.0/uploads</pre> Alternatively, you can just use cp: <pre>$ cp -r /var/www/icaatom_old/uploads /var/www/icaatom-1.3.0/uploads</pre>
 +
# Dump the contents of your old database to a temporary file:<pre>$ mysqldump -u username -p old_database > /tmp/database.sql</pre>
 +
# Now, load the contents into the new database:<pre>$ mysql -u username -p new_database < /tmp/database.sql</pre>
 +
 
 +
== 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
 +
 
 +
<div class="text-alert">This is the most critical step in this upgrade guide. If you get an error, please read our FAQ below to troubleshoot any problems.</div>
 +
 
 +
== 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 [[qubit:Rebuild search index|rebuild the search index]] after upgrading:
 +
 
 +
$ php symfony search:populate QubitSearch
 +
 
 +
== Clear cache ==
 +
 
 +
Clear your [http://www.symfony-project.org/book/1_0/12-Caching cache] to remove any out-of-date data from the application,
 +
 
 +
$ php symfony cc
 +
 
 +
See [[qubit:Clear cache|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.
 +
 
 +
<div class="note">
 +
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!
 +
</div>
 +
 
 +
= 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. [[qubit:Rebuild search index|rebuild the search index]])  and you get an error like
 +
 
 +
<pre>Fatal error: Class QubitActor contains 4 abstract methods and must therefore be declared abstract or implement the remaining methods ...</pre>
 +
 
 +
You need to [[qubit:Clear cache|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 [https://groups.google.com/forum/?hl=en&fromgroups#!newtopic/ica-atom-users 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.<br />
 +
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 [[qubit:FAQ|FAQ]]. Also, try searching the [https://groups.google.com/forum/?hl=en&fromgroups#!forum/ica-atom-users 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 [https://groups.google.com/forum/?hl=en&fromgroups#!newtopic/ica-atom-users ICA-AtoM Users discussion list], and be sure to include:
 +
 
 +
# A subject line that briefly describes the problem (e.g. "Error when I try to run tools:sql-upgrade")
 +
# A detailed description of how to reproduce the problem
 +
# Send us a screenshot of the error, and attach it to your post
 +
# Which version of PHP are you using?

Latest revision as of 15:35, 7 May 2013

Please note that ICA-AtoM is no longer actively supported by Artefactual Systems.
Visit https://www.accesstomemory.org for information about AtoM, the currently supported version.

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?