OpenEMR with aaPanel and LAMP stack on Linux Virtual Machine

This document is a work in progress.

Using a Linux Virtual Machine is an affordable and stable method for running your own instance of OpenEMR. In this tutorial we setup and run Linux version of OpenEMR on Debian Linux having Apache, MariaDB and PHP, hence the LAMP stack, run on that. (Read more about LAMP stack on Amazon's AWS knowledge base).

Rationale

We use a set of free software (or software with free versions available) to run this infrastructure. If you have some spare computational resources available on your daily-use PC, you may run OpenEMR completely free of charge; otherwise you may get a VPS (Virtual Private Server) from a broad number of service providers for a reasonable monthly or annual fee .

Why Linux and not Windows

A number of information technology experts believe that, Linux is

• Less resource hungry
• Less bloated with unused software
• More secure and performant

Why a Virtual Machine

Running on a virtual machine might be a suitable option if :

• You already own a Windows PC but want benefits of Linux (See section above)
• You want to achieve peace of mind by not mixing your daily use of PC with OpenEMR's execution environment (even if your daily-use PC already runs Linux).
• Your own hardware has spare computing resources and you want to run the solution for free of charge (Method 2)
• You do not have suitable hardware readily at hand, but renting computation resources is an option (Method 1)
• You want a portable and scalable solution to increase capacity or power over time.
• You need easy and turnkey backup and disaster recovery methods.
• You want to keep your instance always on or easily access from anywhere (Method 1)

Why aaPanel

With aaPanel we get:

• Effortless installation of the required version of software needed to host and run OpenEMR.
• Easy backup of data in manual and auto-run periodical schemes

Requirements

• You need to decide where would you like to run the virtual machine:
  • On your hardware (Method 2), or;
  • In a datacenter or cloud service provider (Method 1)
• You have admin access to one or more office/clinic PC(s), and optionally
  • additional devices connected via a router or access point to each other (or to the Internet for Method 1).

Steps

Install or Deploy Linux

Install a variant of Debian compatible Linux. We proceed with Debian 12, but you may choose other distribution such as Ubuntu 22 for example (at the time of writing this article this is a default recommendation for aaPanel that we are going to install next )

• You need to create a Virtual Machine with the following specification:
  • Operating System: Debian Linux 12
  • Memory: 4G+ RAM,
  • CPU : 4Core+ CPU
  • Storage: 40GB+ Disk Space
  • Access : Console or SSH access

Method 1 : Run on cloud

NOTE: If you are renting a VPS from a service provider, they usually allow you to choose the desired operating system and its version at the time of creation and you do not need to download the operating system's DVD/ISO image. Debian 12 that we use in this tutorial is very popular among providers and possible is listed among your options. Depending on your chosen provider, you will see something similar to this when creating your instance:

Method 2 : Install on your own hardware

If you are running Virtual Machine (HyperVisor) on your own hardware, you need to download the ISO image and install the operating system yourself.

In this tutorial we give information about how to run a Linux virtual machine on your Windows PC using Broadcom's VMWare Workstation Free Edition. You may use other hypervisors of your choice such as Oracle's VirtualBox, KVM, QEMU, etc on your host operating system as well.

• Go to broadcom.com site then search for and download "VMware Workstation Pro 25H2 for Windows" (free signup might be required). If your own PC already runs Linux as the main operating system, download the other version accordingly in this step.

• Install the VMware Workstation software and create a new Debian 12 x64 machine inside it.

• Go to debian.org and download your desired version of this Linux distro (In this tutorial we use version 12, but you are free to try version 13 that is also available at the time of writing this article)

Install aaPanel

Go to aaPanel.com, then find and copy the installation one-liner command for the free edition.

When the installation is finished, you will be presented with a URL along with a username and a password. Take note and keep a copy in a secure place to be able to login to this panel for the next steps in this tutorial and for the future when you want to backup your database and download a copy of it to save on a redundant storage medium.

Install LAMP

Well L was standing for Linux which we have already installed. Lets got to install the remaining requirements to run OpenEMR. Uppon first login to aaPanel, the wizard will ask you about the technologies you want to use. In this tutorial we will select a collection of technologies working perfectly together that is called LAMP. To do this, change the web server from default "NginX" to "Apache" and ensure that MariaDB, and PHP are also selected. Opetionally select an additional checkbox to install PhpMyAdmin for easier backup and restore operations.

Configure PHP Extensions

OpenEMR requires the mbstring extension of PHP to be installed. To do so, in the aaPanel, go to the "App Store", browse "Installed" section (since we already installed PHP via LAMP and just we want to configure it). Then find PHP in the installed applications and click settings. In the navigation panel choose extensions and scroll down until you find mbstring. Click its install button. (All steps shown in the figure below)

Create Blank website and database

In this phase, inside the aaPanel, under the websites section, create a new website. When the wizard asks you, choose PHP 8.3

Please take note of the database username and the related autogenerated password. we will use them during the configuration phase.

Download OpenEMR

We will use the "Remote download" feature to download the OpenEMR's tar.gz archive (that is a typical format used in Linux software distribution). To do so, in the aaPanel, go to the files section. Then in the file manager navigate to www/wwwroot/oemr.local. Then from the "file operations" choose "remote download". The dialog shown in the figure below will appear and allow you to enter the URL and specify a name to download the content from the URL and save it under that name. Optionally take note of the presented md5 checksum and then copy the download URL from here and paste it in the "URL address" section. type a desired name such as "openemr-7.0.4.tar.gz" in the "File name" field and confirm the download operation.

Wait until the download finishes

After download, optionally compare the downloaded file's md5 checksum against the original distribution to make sure of a healthy download. You may do this by going to the "Terminal" section of your aaPanel and issuing the md5sum command passing the downloaded file's path as argument.

Go back to "Files" section and Unzip the downloaded file. To do this right-click on the file and choose Unzip. In the decompression dialog press confirm to begin unzipping.

NOTE: change the target folder name to "openemr" by removing suffix characters that were appended, or you may

Register Domain

This applies to Method 1 only.

Setup CDN

This applies to Method 1 only.

Create DNS Records

This mainly applies to Method 1. Your modem/router/access point may allow you create static mapping between IP Addresses and names. In this case if for example your virtual machine has been assigned IP address of 192.168.100.24 (acquired through DHCP server on your local network or on the one virtually present in your virtualization platform), you may find it use full to create a mapping so that the name oemr.local resolves to ip address 192.168.100.24. Having this, you do not need to enter the IP address in your browser and instead of http://192.168.100.24, you may simply use http://oemr.local

Create SSL Certificates

This applies to Method 1 only.

Backup and Recovery

Using the approach in this article, there are a number of backup and restoration methods available to you in case you encounter an problem.

Backup whole Virtual Machine

Difficulty		Requirements
Backup	Restore	Storage	Time
Easy	Easy	High	High

The virtualization platform we used in this article supports "Open Virtualization Format" also known as OVF. Using this feature, you can backup everything you deployed in a single portable file that can be easily recovered and get back to operation on the same hardware or on a different one with the ease of a few clicks. If you create and keep this backup, in case you loose your Laptop/PC, the only thing you need to install on your new computer is just the VMWare Virtualization software.

NOTE: In case you opted to run your cirtual machine on a cloud VPS, you may use their built-in backup methods provided by the datacenter (that is normally made available via purchasing extra add-ons), or you may choose other completely free backup methods below.

aaPanel Full Backups

Difficulty		Requirements
Backup	Restore	Storage	Time
Easy	Medium	Medium	Medium

The aaPanel data files and configurations along with websites and their databases can be backed up inside the aaPanel. If you keep such backup in case of disaster you will need to install a Fresh Debian linux and aaPanel

Individual Database and Site Backups

Difficulty		Requirements
Backup	Restore	Storage	Time
Easy	Hard	Low	Low

The PhpMyAdmin component of aaPanel allows you to save dumps of your Mariadb database. This is the most space efficient method to keep backups but the most time consuming one to recover. In case you keep such backups, to recover you have to install Linux, aaPanel, create sites, restore databasem, download and extract the openemr software and adjust the configuration files to point to your db