OpenMRS Standalone
OpenMRS Standalone provides a simplified, all-inclusive installation option with both an embedded database and web server. You can have a local copy of OpenMRS running within minutes: simply download and expand the archive, and then run the extracted openmrs-standalone.jar
file. Your browser will open a new instance of the OpenMRS system. For the OpenMRS Standalone -Reference Application 2.10.0 edition, the default username is "admin" and the default password is "Admin123". And for the OpenMRS Standalone - Platform 2.3.0 edition, the default username is "admin" and the default password is "test". OpenMRS Standalone is a great way to evaluate and explore OpenMRS capabilities. It may also be useful for small-scale production environments. At this time we are still developing operational experience with the standalone in production environments.
Since the embedded database & server are production-quality and the OpenMRS code is the same as our enterprise release, we have high expectations for the standalone. Before you choose the standalone, be aware that we are still gaining experience with this version in production environments. If you have any questions or concerns, let us know through our mailing lists, Twitter (@openmrs), etc. We're listening!
FWIW, we have heard of more than 100 sites, which have successfully used the standalone version, in production, for a number of years. https://talk.openmrs.org/t/using-the-openmrs-standalone-version-in-production/17519
Installation
If you have no prior development experience there is a "For Dummies" version of the installation instructions (see child page), else continue with the instructions below
Step 1
Download and unzip the standalone file
Step 2
Just double click on the openmrs-standalone.jar file in that folder, or execute it as below:
java -jar openmrs-standalone.jar
OpenMRS will install itself the first time it is run. The installer will offer an option to install demo data (demo concepts and/or patient data).
Java version less than 1.8 installed, the standalone may fail to start. You can run the standalone with a specific version of Java by giving the full command line to the java executable. For example:
"c:\Program Files\java\jdk1.8.0_172\bin\java.exe" -jar openmrs-standalone.jar
See below for a list of command line options.
Do NOT delete or rename folders after decompressing the standalone package. They are used by the standalone jar file and it expects them to be in the exact locations where they already are.
- 1 Installation
- 2 GUI Mode Options
- 3 Command Line Mode Options
- 4 Authentication Information
- 5 How to connect to the MySQL database
- 6 How to change the embedded Tomcat memory
- 7 How to run the embedded Tomcat in debug mode
- 8 How to upgrade OpenMRS in a Standalone
- 9 How to profile with YourKit
- 10 Tips
- 11 Frequently Asked Questions
- 12 Known Issues
- 13 Request New Feature or Report Bug
- 14 Technical Documentation
GUI Mode Options
Tomcat Port | This is the port at which to run Tomcat |
MySQL Port | This is the port at which to run MySQL |
File → Quit | This stops Tomcat and MySQL and then closes the application |
File → Launch Browser | This opens the OpenMRS login page for the current web application context |
File → Clear Output | This clears the output log in the user interface text area, but does not clear the log file written on the file system |
Start | This button runs Tomcat, which will automatically start the MySQL database engine if it was not already running. For the embedded MySQL, the first connection automatically starts the MySQL engine |
Stop | This button stops Tomcat and then also stops the MySQL database engine, without closing the application |
Command Line Mode Options
-commandline | Run from the commandline |
-mysqlport | Use to override the MySQL port in the runtime properties file |
-tomcatport | Use to override the Tomcat port in the runtime properties file |
start | Use to start the server |
stop | Use to stop the server |
browser | Use to launch a new browser instance |
-noninteractive | No prompting, installs demo data |
-noninteractive -expert | No prompting, installs without demo data (just basic metadata) |
-noninteractive -empty | No prompting, installs with an empty database |
Authentication Information
After running the standalone jar, it will take you to the OpenMRS log in web page where you can log in with the following default username and password:
OpenMRS username: admin
OpenMRS password: Admin123 or test
The MySQL database has these credentials by default:
MySQL username: openmrs
MySQL password: randomly generated at initial startup. Look in openmrs-runtime.properties
file under connection.password
How to connect to the MySQL database
Go to the extracted standalone folder and copy the password from the openmrs-runtime.properties
file. Then go to the database/bin folder and execute this at the commandline:
./mysql -u openmrs -p
That will prompt you for a password which you copied from the openmrs-runtime.properties
file.
If you are using graphical tools like Navicat and others, just create a new connection and enter the appropriate properties of username, password, port, etc as in the run-time properties file.
If running windows, then you can change the above command to: mysql.exe -u openmrs -p
If you are running multiple instances locally and want to specify a port, you can use something like this:
How to change the embedded Tomcat memory
You can override the default tomcat memory by changing these values in the "vm_arguments" run-time properties file property as below:
vm_arguments=-Xmx512m -Xms512m -XX:PermSize=256m -XX:MaxPermSize=256m -XX:NewSize=128m
How to run the embedded Tomcat in debug mode
You can run the embedded tomcat in debug mode by appending values to the "vm_arguments" run-time properties file property as below:
vm_arguments=-Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5000
After starting the standalone with those vm arguments, if you are using an IDE like eclipse,
Go to "Run->Debug Configurations...". Click on "Remote Java Applications", then click "New". Type in the title. Set the port as 5000 and click the Debug button. Feel free to change the port to any other value.
How to upgrade OpenMRS in a Standalone
How to profile with YourKit
You can profile the standalone with YourKit by appending values to the "vm_arguments" run-time properties file property as below:
vm_arguments=-agentpath:<full agent library path>
This is an example: vm_arguments = -agentpath:/Projects/YourKit_Java_Profiler_11.0.8.app/bin/mac/libyjpagent.jnilib
You can get details of the vm arguments from: http://www.yourkit.com/docs/10/help/agent.jsp
Tips
If you already have an installed instance of OpenMRS and do not want the standalone one to use the same database, you need to do three things:
In the standalone extracted folder, rename the
openmrs.war
file in "tomcat/webapps
" to something different. e.gopenmrs-1.7.war
,openmrs-1.8-beta.war
,openmrs-1.8.war
, etc.In the standalone extracted folder, rename the run time properties file to a name corresponding to the one you have given the war file. e.g the above three examples would have the following respective run time properties file names:
openmrs-1.7-runtime.properties
,openmrs-1.8-beta-runtime.properties
,openmrs-1.8-runtime.properties
Finally delete the openmrs folder (which was expanded from the war file) from the "
tomcat/webapps
" directory.
If you try connecting to the MySQL server from commandline and get this error message: "
ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/tmp/mysql.sock' (2)
":Add this "
&server.socket=/tmp/openmrs.sock
" (without the double quotes) at the end of the value in theconnection.url
key of the runtime properties file, and then restart the standalone application. If after doing that, you still get the same error message, then on your command line, add this: --socket=/tmp/openmrs.sockThen you can connect with something like: ./mysql -u openmrs -p --socket=/tmp/openmrs.sock
If you have any server-side parameter that you want to add or used to add in the my.cnf file, simply add it to the
connection.url
in the runtime properties file in this format:&server.parametername=value
.For instance, if you wanted something like:
max_allowed_packet=32M
, you would add it as:&server.max_allowed_packet=32M
If you choose Expert Mode on the first time standalone screen, you will go through the database setup wizard where you will enter the mysql user name as openmrs and the password should be copied from the runtime properties file under a key named: connection.password
Frequently Asked Questions
Visit our Standalone FAQ section for a detailed FAQ list.
Known Issues
Request New Feature or Report Bug
Please create a ticket in our issue tracker under the "OpenMRS Standalone" project.
Technical Documentation
The standalone is an executable jar. Inside the jar is a Java embedded MySQL jar and an embedded Tomcat jar. (TODO, add links to mysql and tomcat pages) The Tomcat home folder is the directory where you unzipped the standalone. The tomcathome/webapps already has the openmrs war file inside of it, ready to be run. When you execute the standalone jar, MySQL and Tomcat are started on open ports. Because the openmrs war file is in the tomcat webapps directory, it starts automatically.
Code for the standalone can be found in git: https://github.com/openmrs/openmrs-standalone
See the readme.txt file in the openmrs standalone code for instructions on how to build, package, and release the standalone application.
OpenMRS Standalone provides a simplified, all-inclusive installation option with both an embedded database and web server. You can have a local copy of OpenMRS running within minutes: simply download and expand the archive, and then run the extracted openmrs-standalone.jar
file. Your browser will open a new instance of the OpenMRS system. The default username is "admin" and the default password is "Admin123".
OpenMRS Standalone is a great way to evaluate and explore OpenMRS capabilities. It may also be useful for small-scale production environments. At this time we are still developing operational experience with the standalone in production environments.
- 1 Installation
- 2 GUI Mode Options
- 3 Command Line Mode Options
- 4 Authentication Information
- 5 How to connect to the MySQL database
- 6 How to change the embedded Tomcat memory
- 7 How to run the embedded Tomcat in debug mode
- 8 How to upgrade OpenMRS in a Standalone
- 9 How to profile with YourKit
- 10 Tips
- 11 Frequently Asked Questions
- 12 Known Issues
- 13 Request New Feature or Report Bug
- 14 Technical Documentation