OpenClinica User Manual/MultipleInstances

A single webserver can be configured to serve multiple instances of OpenClinica. Alternatively, multiple Tomcat servers can be set up on a given webserver.

Copying an existing instance

Probably the simplest way to setup another instance is to copy an existing instance.

• Gerben details a method in Linux in Setting up a test-environment.
• Backup and restore details how to backup and restore an existing instance to a new instance.

Deploying a new instance from scratch

You can deploy a new instance from scratch, in a similar way to deploying a simple OpenCinica instance. Note that links in this document are for the OpenClinica Linux documentation, similar sections can be found in the Openclinica Windows documentation

1. You need to create a differently named database (just the db, not a new role) such as ‘newtrial’ (following section 9.1.7 of the OpenClinica installation guide)

1. Copy the OpenClinica war file (as per section 9.1.8) as ‘newtrial.war’ (the next section in the manual mentions webservices, which I haven’t used). Start Tomcat (if it isn’t already running) to deploy the ‘newtrial’ folders and the database structure.

Separating out the log files

You can separate out the log files from different instances by updating the datainfo.properties file, found in:

${catalina.home}/webapps/${WEBAPP.lower}/WEB-INF/classes/datainfo.properties

Update the log.dir line to put the logs in a separate directory:

log.dir=${catalina.home}/logs/newtrial/newtrial

Restart the instance in Tomcat (or Tomcat itself) for these changes to be picked up.

Managing multiple instances

To properly stop instances of OpenClinica you will need to fully stop Tomcat. Once Tomcat is fully stopped, you can move files and update the database in an unrestricted manner. The current version of OpenClinica (3.1.2) does not clean up after itself if the instance has been stopped in Tomcat Manager (e.g. http://localhost:8080/manager/html ). One benefit of running multiple Tomcat servers is that the number of instances on a given server is reduced, so in the event of needing to stop an instance by stopping Tomcat, the number of instances affected is reduced.

The benefits and drawbacks of setting up multiple Tomcat servers (benefit: each instance is independent; drawback: increased resource consumption - memory used by Tomcat), versus the number of instances served from each (benefit: shared use of resources; drawback: dependence on a single Tomcat instance) should be weighed up.

Ensuring Tomcat doesn't run out of memory

Running a number of instances can cause the Tomcat to run out of memory if you don’t tweak Tomcat’s configuration (increasing the MaxPermSize setting). OpenClinica's Linux doc states:

"The MaxPermSize value depends on the number of war files that you are deploying. The web war needs a 180m of PermGen and the ws war needs a 90m of PermGen memory settings." (the Windows doc has a similar note)

The PermGen (Permanent Generation) memory is allocated separately to the regular (Heap) memory (a.k.a. the Xmx setting in Linux and the 'Maximum Pool Size' setting in Windows) [1]. Consequently, if your server doesn't have much memory, you may need to reduce the memory allocated to the Heap to allow you to increase the memory allocated to Permanent Generation. This can be achieved by reducing the Xmx setting (in Linux) or the 'Maximum Pool Size' setting (in Windows) and increasing the MaxPermSize setting by an equivalent amount.

Replicating user account passwords to a new instance

You can use replicate an existing user password to a new instance (so they can reuse their password for a new instance). This can be achieved by copying the value of the 'passwd' field (actually the SHA1 hash of the password) in the 'user-account' table for that user from the old instance to the new instance. If the user hasn't previously logged in (e.g. you have just created the account), you can set the passwd_timestamp to the current date (as if the user has just set their password).

This achieves a similar effect to a single instance in that a single username and password can access multiple studies (but via different URLs). There is extra burden that if passwords change, then they may need to be re-set on all instances.

Reusing passwords is in general bad, particularly if they are used for different purposes under different security regimes, such as a bank account password being reused for an insecure OpenClinica instance or a live OpenClinica instance password being reused for an insecure public OpenClinica instance.