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.
These instructions detail how to set up a server using a community-contributed snapshot of an Ubuntu 10.10 server with Java, MySQL, and Tomcat pre-installed. While this makes setup quick, it might not be ideal for a production environment.
If you simply want to run a demo, it's much simpler to run the OpenMRS appliance on your own computer.
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.
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.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.
You can accept the defaults in Advanced Instance Options. Optionally, add a key/value tag to the instance (e.g., "dev").
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.
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:
ssh -i your_keypair_file.pem ubuntu@your_dns
-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 namedubuntu
. 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:
sudo service tomcat6 restart
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 :
mkdir /usr/share/tomcat7/.OpenMRS
Change permissions group:
chown tomcat7 /usr/share/tomcat7/.OpenMRS
Grant write permissions for tomcat7 group. Initial permissions are 744.
chmod 774 /usr/share/tomcat7/.OpenMRS
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.
If the installation began properly, but shows the installation screen again with a "can't create openmrs-runtime.properties" error, check the logs at /var/log/tomcat7/catalina.out
. It may mean the OpenMRS installation failed.
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.