Mirth Connect on Ubuntu 24.04 on Azure User Guide

Overview

Mirth Connect, now published as NextGen Connect, is the most widely deployed open source healthcare integration engine. It is an interface engine: you build channels that receive, filter, transform and route clinical messages between disparate systems. Mirth Connect speaks the languages of healthcare interoperability out of the box, including HL7 v2 and v3, FHIR, X12, DICOM, XML, JSON and delimited text, and it can move those messages over MLLP, TCP, HTTP, file, database, SFTP and more.

The cloudimg image installs Mirth Connect 4.5.2 (MPL 2.0) on OpenJDK 17, running as a dedicated mirth service user under systemd. Mirth is HTTPS native and its web admin plus REST API listen on the loopback address 127.0.0.1:8443 only. nginx terminates TLS on port 443 with a per-VM self signed certificate and reverse proxies to the loopback listener, so the admin surface is never exposed in the clear. Port 80 serves an unauthenticated health endpoint and redirects everything else to HTTPS. The embedded Apache Derby database, the auto generated keystore and the configuration map live under /var/lib/mirthconnect on a dedicated Azure data disk. A unique admin password is generated on the first boot of every VM, and the shipped default admin / admin login is proven disabled before the image ships. Backed by 24/7 cloudimg support.

What is included:

• Mirth Connect 4.5.2 build b363 (NextGen Connect, MPL 2.0), verified by sha256 at build time
• OpenJDK 17 headless JRE, running Mirth as the mirth system service (mcserver.service)
• The Mirth admin and REST API bound to 127.0.0.1:8443 (loopback only)
• nginx terminating TLS on :443 (per-VM self signed certificate) and reverse proxying to the loopback listener
• Port 80 serving an unauthenticated /healthz endpoint and redirecting all other traffic to HTTPS
• The default admin / admin login rotated to a unique per-VM password on first boot, recorded in a root only file
• A dedicated Azure data disk at /var/lib/mirthconnect holding the embedded Derby database, keystore and configuration map
• mcserver.service + nginx.service as systemd units, enabled and active
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet plus subnet in the target region. Standard_B2ms (2 vCPU / 8 GiB RAM) is a reasonable starting point; size up for higher message throughput and more concurrent channels. NSG inbound: allow 22/tcp from your management network, and 80/tcp plus 443/tcp for the web admin and REST API. Mirth channels open their own inbound listener ports (for example an HL7 MLLP listener on TCP 6661); those are defined per channel, so open only the specific ports your channels use (see Step 13). The appliance ships a self signed certificate, so for production put your own domain and a trusted certificate in front of it (see Maintenance).

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Mirth Connect by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22), HTTP (80) and HTTPS (443). Review the dedicated data disk on the Disks tab, then Review + create then Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name mirth-connect \
  --image <marketplace-image-urn> \
  --size Standard_B2ms \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

az vm open-port --resource-group <your-rg> --name mirth-connect --port 80 --priority 1010
az vm open-port --resource-group <your-rg> --name mirth-connect --port 443 --priority 1020

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the services are running

systemctl is-active mcserver.service nginx.service

Both report active. Mirth Connect runs as a Java service (the mcserver launcher) bound to the loopback address 127.0.0.1:8443 for HTTPS and 127.0.0.1:8080 for HTTP, and nginx fronts it: TLS on port 443, plus a port 80 health endpoint and HTTPS redirect. Mirth's embedded Derby database and keystore live on the dedicated Azure data disk mounted at /var/lib/mirthconnect.

Step 5 - Retrieve your admin password

The Mirth admin password is generated uniquely on the first boot of your VM and written to a root only file:

sudo cat /root/mirthconnect-credentials.txt

This file contains MIRTH_USERNAME (always admin), MIRTH_PASSWORD, the web admin URL and the REST API base. Store the password somewhere safe. The file is mode 0600 and owned by root, so only an administrator can read it. The relocation of the Derby database, keystore and configuration map onto the data disk is shown below.

Step 6 - Confirm the health endpoint and the TLS edge

nginx serves an unauthenticated health endpoint for load balancers and probes, and terminates TLS in front of the loopback Mirth listener:

curl -s -o /dev/null -w 'healthz: HTTP %{http_code}\n' http://127.0.0.1/healthz
curl -s -o /dev/null -w 'port 80: HTTP %{http_code}\n' http://127.0.0.1/
curl -sk -o /dev/null -w 'web admin over TLS: HTTP %{http_code}\n' https://127.0.0.1/

/healthz returns HTTP 200 and never requires authentication, so it is safe for an Azure Load Balancer health probe. Port 80 returns HTTP 301 and redirects to HTTPS; the web admin at https://<vm>/ returns HTTP 200 over TLS.

Step 7 - Verify the per-VM admin password over the REST API

Mirth ships the default login admin / admin. On the first boot of your VM that default is rotated to your unique per-VM password using the Mirth REST API, and the default is then proven disabled. You can confirm the same from the command line. The Mirth REST API requires an X-Requested-With header on every call. Because the command embeds your unique password, run it interactively rather than from a script - substitute the value of MIRTH_PASSWORD from Step 5 for <MIRTH_PASSWORD>:

mirth_login() { curl -sk -H 'X-Requested-With: cloudimg' -H 'Accept: application/json' \
  --data-urlencode username=admin --data-urlencode "password=$1" \
  https://127.0.0.1/api/users/_login | tr -d ' \n' | grep -oE '"status":"[A-Z_]+"' | head -1; }
echo -n "default admin/admin  -> "; mirth_login 'admin'
echo -n "your per-VM password -> "; mirth_login '<MIRTH_PASSWORD>'

The default admin / admin prints "status":"FAIL" (the shipped default has been disabled), while your per-VM password prints "status":"SUCCESS". A FAIL status means the credentials were rejected; SUCCESS means the session authenticated. Mirth's own password policy is left at its defaults, which you can tighten in conf/mirth.properties.

Step 8 - Sign in to the web admin

Browse to https://<vm-public-ip>/. The appliance uses a self signed certificate, so accept the browser warning (or, for production, put your own domain and certificate in front - see Maintenance). Mirth Connect shows its landing page. Sign in to the Web Dashboard with the username admin and the password from Step 5, or click Launch Mirth Connect Administrator to download and run the full desktop Administrator, which is where you design and deploy channels.

Step 9 - Explore the REST API

Everything the Administrator does is also available over the REST API, and the appliance ships an interactive Swagger explorer at https://<vm-public-ip>/api/. This is the NextGen Connect Client API, grouped by area: Channels, Channel Deployment Operations, Channel Statistics, Messages, Users, Server Configuration and more. Use it to script deployments, integrate with CI, or drive Mirth from your own tooling.

Step 10 - Build and manage channels via the API

Expand the Channels group in the API explorer to see the full channel lifecycle: GET /channels to list channels, POST /channels to create one, PUT /channels/{channelId} to update it, DELETE /channels/{channelId} to remove it, plus deploy, undeploy, enable and summary operations. A channel defines a source connector (for example an HL7 MLLP listener), a set of transformers and filters, and one or more destination connectors. Design channels in the desktop Administrator, then use these endpoints to deploy and manage them at scale.

Step 11 - Manage users

The Users group exposes the user management endpoints, including GET /users to list users, POST /users to create one, and the POST /users/_login and PUT /users/{id}/password calls that this appliance uses on first boot to rotate the admin password. As the administrator you can add operators, assign them channels, and manage passwords entirely over the API.

Step 12 - Confirm data lives on the dedicated disk

Mirth's data - the embedded Derby database (channels, message history, users), the auto generated keystore and the configuration map - is stored under /var/lib/mirthconnect on the dedicated Azure data disk, so it survives OS changes and can be resized independently:

findmnt /var/lib/mirthconnect
ls -1 /var/lib/mirthconnect/appdata

The mount is backed by a separate Azure data disk captured into the image and re-provisioned on every VM. The mirthdb directory is the Derby database and keystore.jks is the server keystore.

Step 13 - Open channel listener ports

Mirth channels receive messages on ports you choose per channel - for example an HL7 v2 MLLP listener commonly uses TCP 6661, or a channel might listen for HTTP on another port. The image deliberately does not pre-open a wide range. When you deploy a channel with a TCP or HTTP listener, open exactly that port in the Azure network security group:

az vm open-port --resource-group <your-rg> --name mirth-connect --port 6661 --priority 1030

Bind channel listeners only to the interfaces you need, and prefer TLS-enabled connectors for any traffic that leaves the host.

Maintenance

• Password: the admin password is set on first boot and recorded in /root/mirthconnect-credentials.txt. To change it, sign in to the Administrator and use the user settings, or call PUT /api/users/1/password over the REST API.
• TLS and your own domain: the appliance ships a per-VM self signed certificate on port 443. For production, point a DNS name at the VM and install a trusted certificate (for example with certbot / Let's Encrypt), then reference it in the nginx site at /etc/nginx/sites-available/cloudimg-mirth-connect and reload nginx.
• Channels: design and deploy channels in the desktop Administrator (launched from the landing page), or manage them over the REST API under /api/channels.
• Upgrades: Mirth Connect is installed under /opt/mirthconnect; your data under /var/lib/mirthconnect is preserved across restarts. Test upgrades against a copy of your data disk first.
• Storage: all Mirth state lives under /var/lib/mirthconnect on the data disk; back up that volume to protect your channels and message history.
• Security patches: unattended-upgrades remains enabled so the OS continues to receive security updates automatically.
• Compliance: this image ships as infrastructure only. You are responsible for all HIPAA and PHI controls, including encryption in transit and at rest, network isolation, access control and audit. cloudimg does not imply certified compliance.

Support

cloudimg provides 24/7 expert support for this image. Contact support@cloudimg.co.uk.