Editing Safe Upgrading (section)

==Preparation==

If you are upgrading then there are a number of precautions you can take to ensure the process runs as smoothly as possible. It is impossible to give 100% cast iron guarantee an upgrade will succeed particularly if you have a heavily customised repository so you must make sure that you are in position to roll back in the unlikely event that the upgrade does not go to plan.

It is worth saying at this point that if possible you can ease your fears by performing this task on a development server as a practice run. This technique if available to you is strongly advised.

To prepare you should:

===Tell an adult===

Talk to your system administrator about getting a full system backup made. It is advisable to do this fairly regularly anyway in case of hardware failure or fire (see [[Backups|backing up]]).

You should also speak to who ever you need to get permission from to cause server down time. This is not always required as many upgrades can be done with very little down time but it is best to ask for permission and not use it than find you have to apologize for an unexpected service outage.

===Create a backups directory===

 mkdir <eprints_root>/backups

To create a directory to put backups into.

===Check you have enough disk space===

 df -h

Will give you a table:
<pre>
Filesystem            Size  Used Avail Use% Mounted on
/dev/sda5              32G  1.4G   31G   5% /
/dev/sda7              32G   22G   11G  67% /opt
/dev/sda8              41G   24G   18G  59% /usr
/dev/sda6              16G  6.2G  9.9G  39% /var
/dev/sdb1             135G   24G  105G  19% /backup
</pre>

You should make sure that the disk which contains your eprints directory (usually /opt or /usr) is over 50% free. The backup of the archive will take up a similar amount of space to the archive itself so you should check you have enough space for it before starting.

===Backup your database===

 cd <eprints_root>/backups

to change to your backups directory

 mysqldump -u <db_user> -p <db_name> > <archive_id>.archive.backup-<year>-<month>-<day>.sql

at the prompt you will need to enter the ''password''. If your repository is large this step can take a while. The purpose of the elaborate file name is so that at a glance you can tell what this file is. Also if you have multiple backups then ordering them alphabetically will put the backups for that archive in date order so you can find your most recent backup. Ending the file with .sql means you know it is a database backup. 

If you do not know your <code>db_user</code>, <code>db_name</code> or ''password'' for the above step you can find it by typing:

 cat <eprints_root>/archives/<archive_id>/cfg/cfg.d/database.pl

You should now have a .sql file containing your database backup in your <eprints_root>/backups directory.

===Backup your archive===

 cd <eprints_root>/archives/

and then

 tar czf <eprints_root>/backups/<archive_id>.archive.backup-<year>-<month>-<day>.tgz <archive_id>

to create a zipped backup of your entire repository including static pages, documents, files and configuration. This can take a long time, for large repositories it can be several hours.

Depending on the output of
 du -sh {var/xapian,html}
you may prefer if you are short of disk space  to exclude some big directories which are reproducible (maybe in some hours!). If it makes sense for you backup
your archive by
 tar --exclude=<archive_id>/{var/xapian,html} -cvzf <eprints_root>/backups/<archive_id>.archive.backup-<year>-<month>-<day>.tgz <archive_id>

===Backup your perl_lib===

This step should not be necessary if you have followed the guide for [[Tips_to_write_plugins|making safe plugins]]. If you didn't follow the guide and modified <code>perl_lib</code> (for shame) or you are particularly paranoid you may want to backup your <code>perl_lib</code> directory.

 cd <eprints_root>

and then

 tar czf backups/<archive_id>.archive.backup-<year>-<month>-<day>.tgz <perl_lib>

You should now be ready to upgrade.