Mirth Connect: Part 1 - Getting Started with 🐳 Docker
Mirth Connect is how most healthcare orgs still move HL7v2 messages. Setup from scratch: configuring channels, parsing message types, sending and receiving messages without losing your mind.
The Connect container maps only port 8443, so a channel deployed inside it can't receive messages until you map that channel's port too.
Removing a container that runs on the embedded Derby database deletes the database with it, including all your channels and messages.
Passing credentials as command-line arguments exposes them in process listings, so put them in the mirth_properties Docker Secret instead.
Questions people ask
How do I run Mirth Connect in Docker?
Pull the image with `docker pull nextgenhealthcare/connect`, then start it with `docker run --name connect -d -p 8443:8443 nextgenhealthcare/connect`. Connect is then reachable at https://localhost:8443.
Why does sending a message to my Mirth channel in Docker fail?
Only port 8443 is mapped to the host OS. Messages sent to a channel inside the container fail until you map the channel's port as well.
How do I set mirth.properties values with Docker environment variables?
Named variables like DATABASE, DATABASE_URL and VMOPTIONS are passed with `-e` or loaded from a file with `--env-file`. For any other property, use the `_MP_` prefix, replacing `-` with `_` and `.` with `__`. For example, `_MP_DATABASE__READONLY_MAX__CONNECTIONS='25'` sets `database-readonly.max-connections = 25`.
How do I use Docker Secrets with Mirth Connect?
The image supports two secret names. Properties in `mirth_properties` get merged into `mirth.properties`, and options in `mcserver_vmoptions` get added to `mcserver.vmoptions`. After deploying with Docker Compose, check the merge with `docker exec -it connect cat conf/mirth.properties`.
The engine that has run healthcare integrations for twenty years
Getting Started
Head over to Docker and download the application for your OS.
Once Docker is installed and running, pull the latest NextGen Connect Docker image with: docker pull nextgenhealthcare/connect
You should see an image with repository: nextgenhealthcare/connect and tag 'latest'.
Start a Connect container by running: docker run --name connect -d -p 8443:8443 nextgenhealthcare/connect
-name connect names your container connect
d runs your container in the background
p 8443:8443 maps your OS port 8443 to the container's port 8443
nextgenhealthcare/connect tells docker what image to use, in this case the latest image, when creating your container
Connect is now running and you can reach it at https://localhost:8443. One thing to know: only port 8443 is mapped to the host OS. If you deploy a channel inside this container and try to send a message to it, it will fail until you map the channel's port as well.
Check the container status with: docker ps -a
Check the server logs with: docker logs connect
Stop and remove the container with: docker stop connect && docker rm connect
When you remove a container running on the embedded Derby database, the database goes with it — all your channels and messages included. The "Docker Volumes" section below covers how to persist that data.
Configuring
The Connect Docker image supports configuration via environment variables, custom properties files, and Docker Secrets. Here's how each approach works.
Environment Variables
The Docker images support these environment variables natively:
Pass them using the -e parameter. To specify a database type and set a VM option: docker run --name connect -e DATABASE='derby' -e VMOPTIONS='-Xmx512m' -p 8443:8443 nextgenhealthcare/connect
Most environment variables map to entries in Connect's mirth.properties file. For the full list of supported properties, search the User Guide for "mirth.properties".
For any property not covered by the named variables, use the _MP_ prefix syntax: replace - with _ and . with __. To set database-readonly.max-connections = 25, run: docker run --name connect -e _MP_DATABASE__READONLY_MAX__CONNECTIONS='25' -p 8443:8443 nextgenhealthcare/connect
Loading all your variables as command-line arguments gets unwieldy fast. Docker supports loading them from a file instead. Here's an example file (substitute serverip with your actual IP): myenvfile.txt
Use it with Docker: docker run --env-file=myenvfile.txt -p 8443:8443 nextgenhealthcare/connect
Docker Secrets
Passing credentials as command-line arguments means they show up in process listings. Docker Secrets handles this more securely: secrets are encrypted in transit and at rest inside a Docker Swarm, and only services with explicit access can read them while running. Docker Secrets works with Docker Swarm, Docker Compose, and Docker Stack.
The Connect Docker images support two secret names: mirth_properties and mcserver_vmoptions. Properties in mirth_properties get merged into mirth.properties. VM options in mcserver_vmoptions get added to mcserver.vmoptions. Here's how to wire this up with Docker Compose.
Mirth Sync is a command-line tool for synchronizing Mirth Connect code between servers. It handles push and pull for channels, code templates, configuration maps, and global scripts. It integrates with Git and other version control systems for tracking changes over time.
Working with Docker regularly means accumulating unused images, containers, and volumes. They don't cause problems immediately, but they eat disk space and clutter output. These commands keep things tidy.
# Docker provides a single command that will clean up any resources — images,# containers, volumes, and networks — that are dangling (not tagged or associated# with a container).docker system prune
# To additionally remove any stopped containers and all unused images (not just# dangling images), add the -a flag to the command.docker system prune -a# Use the docker images command with the -a flag to locate the ID of the images# you want to remove. This will show you every image, including intermediate# image layers. When you've located the images you want to delete, you can pass# their ID or tag to docker rmi.docker images -adocker rmi Image Image
# Remove Dangling Imagesdocker images -fdangling=true
docker image prune
# Remove By Patterndocker images -a|grep"pattern"docker images -a|grep"pattern"|awk'{print $3}' rmi
