Amazon EC2

If you’ve made it to this page, you’re probably gearing up to set up OpenMRS on Amazon Web Services (AWS) EC2. AWS offers server hosting through its Elastic Computing Cloud (EC2), allowing you to create a virtual server and run OpenMRS on it.

Whether you're preparing for a demo or a more long-term project, this guide will walk you through the steps to get everything up and running.

EC2 servers are virtual machines that can run the same software as your desktop, but without requiring separate hardware. It’s a fast, convenient way to set up a server—ideal for short-term needs or special purposes like testing an upgrade. While AWS is the focus here, remember that other vendors provide similar services.

Prerequisites 

Below are a few concepts you should familiarize yourself with before you begin this process:

Privacy

Like any internet-accessible server, an EC2 instance has security vulnerabilities. Your organization might need to comply with local privacy laws or professional standards for safeguarding patient data. Amazon offers a whitepaper on HIPAA-compliant applications that your legal team should review.

While OpenMRS has settings to mask patient names, this alone isn't enough to ensure privacy. The unmasked data remains in the database and can still be accessed through API calls. For more on how to protect privacy, see our Anonymizing Data guide.

Security

This guide describes how to install a preconfigured Ubuntu server snapshot, but keep in mind that this snapshot was created by an unknown third party. If you’re planning to use it in production, it’s crucial to conduct a security audit or, better yet, create your own image with a clean installation of Ubuntu, MySQL, Java, and Tomcat.

Performance

Before you dive in, consider what you’ll be using this server for. An EC2 instance might need extra configuration to meet your performance requirements.

Survive with a Micro-Instance

For DEMO purposes (not suitable for production):

Amazon EC2 offers a free tier for Micro instances, which is a cost-effective way to host an OpenMRS demo online. However, the OpenMRS web app may not perform well on an AWS micro instance (with 1GB of RAM) under default configurations. Performance can be improved by adding more swap space (e.g., 1GB). Follow the instructions here.

For additional stability and to avoid the java.lang.OutOfMemoryError: PermGen space issue, follow the steps outlined here.

Connectivity

You can’t use your OpenMRS server without a reliable internet connection. Ensure your site has excellent, dependable connectivity.

Project lifespan

How long will you need the server to run? 

The Ubuntu community guarantees Long Term Support for certain versions. Ubuntu 10.10, the version used in this walkthrough, is not a Long Term Support version. If your project will run for a long time, you may prefer to use an AMI with a different version and install Java, MySQL, and Tomcat yourself. 

Amazon Setup

Refer to the Getting Started with EC2 Guide. 

Sign up

The guide begins with instructions on how to sign up to AWS. 

Create an Instance

The "Launch a Server Instance" section walks you through creating a server.

1. On step 2, "Choose an AMI," click the Community AMI tab. Search for ami-cca25ea5, "Ubuntu 10.10 ready for OpenMRS." Click Select.

   UPDATE: ami-cca25ea5 is no longer available on AWS. An image can be built using SDK as explained here. 
   
   

2. On the next screen, select the system configuration from the Instance Type dropdown. Pick an instance type that meets OpenMRS system requirements for your organization's installation.
   
   

3. You can accept the defaults in Advanced Instance Options. Optionally, add a key/value tag to the instance (e.g., "dev").
   
   

4. On step 3 and 4, you'll create a Key Pair—your security credential for connecting to the server later. Save the credential file securely, as it cannot be recreated.
   
   

5. On step 5, "Create a Security Group," add two rules:

   • Enable web browser access:

     • Port range: 80

     • Source (default): 0.0.0.0/0

   • Enable Tomcat manager access:

     • Port range: 8080

     • Source (default): 0.0.0.0/0

   • Keep the rule for port 22 for SSH access.

Once you finish the installation, your instance should be up and running. Now the whole world can access your new server on these ports.

Note the guide's caution about restricting IP addresses that can access your instance, especially if you put sensitive or private data on the server.

Connect to your server

In the getting started guide, continue to "Next: Connect to a Linux/UNIX instance."

Follow the directions to ssh into your new instance. The ssh connect command will be similar to:

• -i identity_file: This is the file you downloaded when you created the Key Pair. It must be in your filepath, or specify the full filepath.

• user@: The Ubuntu installation includes a user named ubuntu. Connect as this user.

• your_dns: AWS creates a DNS hostname for connecting. Find it by opening your AWS console in another window. Expand INSTANCES in the Navigation menu on the left and click on Instances. Your new server will appear in the My Instance area. Click on the row, and the description of your server will appear beneath. Scroll down to the Public DNS address.

Change Default Passwords

As this Ubuntu image is publicly available, others might know the passwords for MySQL and Tomcat Manager. Change the passwords now.

MySQL

No documentation is available about the root user's assigned password on this image. To reset the MySQL root password, follow these instructions here.

Tomcat6

Edit the/etc/tomcat7/tomcat-users.xml file to change the password for the admin user. Restart Tomcat to apply the changes:

Confirm the change by opening a web browser to http://your_aws_dns_here:8080/manager/html.

Change Settings for UTF8

If you're using UTF8, make the necessary configuration changes for MySQL by following the directions here.

There is already a [mysqld] section in /etc/mysql/my.cnf. Don't re-add the [mysqld] line. Insert the new lines anywhere in the section.

Tomcat7 is already set to use UTF8.

Change Java

Follow the Ubuntu instructions to change Java.

Change Tomcat

If you encounter PermGen memory errors with a 1.7.1 install, this might manifest as an installation failure or failure to restart OpenMRS from the Tomcat manager. The log file at /var/log/tomcat7/catalina.out might show an OutOfMemoryError.

To change memory allocations, follow the directions at Troubleshooting Memory Errors to change CATALINA_OPTS. Scroll down to Jonah Mwogi's notes in the comments.

Significant performance improvements were made in OpenMRS 1.8.x, so these changes may not be necessary.

Make a Backup 

Now that you have a pristine server ready to go, it's a good time to take a backup. This allows you to roll back to this snapshot if you need to start fresh later.

In your AWS Management Console, select ELASTIC BLOCK STORE > Snapshots. Follow the directions for creating a snapshot.  

Install OpenMRS

Follow the OpenMRS installation instructions up to Step 6, Configuration.

When you begin configuration, you'll get an error message that tomcat7 isn't allowed to create a directory. You'll have to do it from the Ubuntu command line.

For this example, the directory will be /usr/share/tomcat7/.OpenMRS.  Use the directory that appears in the error message. 

ssh into Ubuntu as before.  

Create the directory :

Change permissions group:

Grant write permissions for tomcat7 group. Initial permissions are 744.

On your web browser, click the Retry button. The installation will continue normally.

When prompted for a database user, use root and the password you chose when you reset root's password.

Additional Reading

For more background, check out Amazon's EC2 overview page and EC2 FAQ. If you prefer command-line tools, the EC2 API tools will let you manage your instance directly.