OpenClinica User Manual/BackupAndRestore

Backup and restore of OpenClinica

Backing up your OpenClinica setup is a must. And not only that: you must practice restoring your backup. You know why, so do it. Having said these grave warnings: backing up your OpenClinica is simple! There are only two things to backup: your database and your study files.

Backing up during the development cycle

Make backups at every step in the process so you can backup to an earlier step if you make a mistake (e.g. once you've entered data there's no easy way to delete that data, or delete rules once you've added them).

Backup at these points:

1. Empty database
2. Study created
3. CRFs
4. Events
5. Rules

As well as making backups, don't forget to make notes on how you've been configuring the study. Presuming you've been working on a test machine, you'll need to follow this guide when you move the study to a live environment. The guide could be a spreadsheet with details of the configuration of the 'Create Study' section, and a sheet listing the Events, their configuration and the CRFs in each.

Windows backup script

The OpenClinica website includes an example of an OpenClinica backup script for Windows.

Backup of the database

Postgres comes with a number of command line utilities and one of them is pg_dump. This utility makes a (huge) text-file with commands to recreate your openclinica database, plus inserts into all the tables.

Let's say your database is called "openclinica" and you are making your backup on 14 July 2010. In Linux you can log in to your server and type:

sudo -u postgres /usr/bin/pg_dump -U postgres openclinica > pg_dump_openclinica_20100714

The syntax is straightforward: pg_dump, followed by the name of the database and then the name of the dump-file. Make the name of this file as descriptive as possible, so do not use just "OC" or "backup", and always add a date to it. As a final step you must take your dump-file off the server and store it somewhere safe. And I repeat: do not leave it on your server!

A command to perform something similar in Windows (your paths may vary):

“C:\Program Files (x86)\PostgreSQL\8.4\bin\pg_dump.exe” --host localhost --port 5432 --username clinica --format custom --blobs --verbose --file C:\oc\backup\pg_dump_openclinica_20100714 openclinica

Backup of the study (data) directory

All your CRF's in XL-format, plus XML-rules files, plus CRF-attached files and also your generated datasets and Metadata-sets are stored in the directory openclinica.data. This directory is located in /usr/local/tomcat/ (or C:\oc\tomcat in Windows). For a complete backup of OpenClinica you should back up this directory to a safe location on a different server. In Linux you can tar this directory in one line with:

tar -cvvf oc_data_20100714.tar /usr/local/tomcat/openclinica.data

In Windows you can use Explorer to copy the directory.

Backup of the application (webapps) directory

To take things one step further, you can back up the application directory that can be found in webapps. The openclinica (or otherwise named) directory is located in /usr/local/tomcat/webapps/ (or C:\oc\tomcat\webapps\ in Windows).

Just backing up your datainfo.properties

Rather than backup the whole application (webapps) directory (which on the whole doesn't change during use), you may want to backup the only file you are likely to have changed - the configuration file datainfo.properties. Usually the information in this file does not change much after the installation of OpenClinica. But in case of a crash, it will save you a lot of time if you have settings like ports and mail-configuration, so in Linux type:

tar -rf oc_data_20100714.tar /usr/local/tomcat/webapps/OpenClinica/WEB-INF/classes/datainfo.properties

Restoring the database

Restoring to a differently named instance

If you wanted to restore your original instance (e.g. openclinica) to a differently named instance (e.g. openclinica2), simply restore the data to a differently named database (openclinica2), rename the data directory (openclinica2.data) and webapps directory (openclinica2). See the Multiple Instances page for more information (e.g. before restarting the new instance, you may want to amend the logging directory, so that it logs to a different directory from the original instance).

Stopping OpenClinica

Restores can only be made when the OpenClinica Application isn't using the database. So either OpenClinica application or Tomcat must be stopped temporarily. The easiest way may be to use the management pages to stop specific applications (Tomcat Manager How-To). Alternatively you can stop Tomcat itself (on Windows this can be done via Windows services or the Windows command line).

Restoring from the dump file

To restore the database you will have to delete the existing openclinica database, recreate it and "run" the dump-file.

In Linux you can do this from the command line:

sudo -u postgres/usr/bin/psql
drop database openclinica 
create database openclinica with encoding='UTF-8' owner=clinica;

Then exit psql (\q) and go to the directory where your dump-file is located and type (as user postgres):

/usr/bin/psql openclinica < pg_dump_openclinica_20100714

This will restore your database.

This process can also be performed in Windows, using the PGAdmin client:

1. Open PGAdmin, browse to and right-click on the openclinica database (Object Browser, Servers, Postgres, Databases, openclinica), select ‘Properties’, then Delete/Drop (or Properties and alter the Name if you want to retain current database)
2. Right-click on Databases, New Database, Name openclinica, click OK.
3. Right-click on the new openclinica database, Restore, find the file and click OK

Creating an empty OpenClinica database

To create a new, empty OpenClinica database, you can skip the final restore step in the steps above. When OpenClinica starts up, it creates a new database structure in the empty database (including resetting the admin password). The uploaded files can also be cleaned out by deleting the contents of openclinica.data.

Restoring the study (data) directory

Restore the data directory to /usr/local/tomcat/ (or C:\oc\tomcat in Windows)

Restoring the application (webapps) directory

Restore the application directory to /usr/local/tomcat/webapps/ (or C:\oc\tomcat\webapps\)