No announcement yet.

Using Connect With Docker


  • Using Connect With Docker

    Click image for larger version  Name:	ArticleConnectDocker_Title.png Views:	0 Size:	56.6 KB ID:	175026

    ​We’re proud to announce that NextGen Connect is now available for use on Docker Hub!

    In the past, NextGen Connect has been available to install and run locally in Windows, Linux, Mac OSX, and our hard and soft Appliance solutions. The developers at NextGen evaluate and use a variety of tools when updating, testing, and debugging Connect. We’ve actually been using Docker for testing Connect for about a year and have found it very convenient and we hope others will too.

    So What is Docker?

    Docker is a platform allowing users to quickly spin up an application in an isolated container.

    Getting Started

    The first thing you’ll need to do is head over to Docker and download the application for your particular OS.

    Once Docker is installed and running, pull down the latest NextGen Connect Docker image with:

    docker pull nextgenhealthcare/connect
    Once that succeeds, you can run the following to view a list of your Docker images:

    docker images
    You should see an image with repository nextgenhealthcare/connect and tag 'latest'.

    Finally, you can start a Connect container by simply 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
    At this point Connect is running and you can interact with it as you normally would (example: open a browser with https://localhost:8443). It’s important to note that only port 8443 has been mapped to the host OS so sending a message to a channel you’ve deployed on Connect running in this container will fail until you map ports for your channels.

    You can check the status of this container with:

    docker ps -a
    And you can check the server logs with:

    docker logs connect
    When you are done, you can stop and remove the container with:

    docker stop connect
    docker rm connect
    Please note the following when starting, stopping, and removing a simple Connect container running on the embedded Derby database: When the Connect container is removed, so is your database, which includes all of your channels and messages. Head to the "Docker Volumes" section to learn about persisting the data.

    Configuring Connect Docker

    Click image for larger version  Name:	ArticleConnectDocker_Switches.jpg Views:	0 Size:	115.8 KB ID:	175041

    So now you are asking yourself, well that’s all well and good, but how do I use a different database? And how do I set my keystore password? Or even change the VM options? We’ve designed Connect Docker so that it can be configured in several ways. The first is by use of environment variables.

    Environment Variables

    Our Docker images natively support the following environment variables:
      • The type of database to use for Connect’s backend (ex: derby, postgres, mysql, oracle, sqlserver)
      • The JDBC URL to use when connecting to the database (ex: jdbc:postgresql://localhost:5432/mirthdb)
      • The username to use when connecting to the database
      • The password to use when connecting to the database
      • The maximum number of connections allowed for the main read/write connection pool
      • The password for the keystore file itself
      • The password for the keys within the keystore, including the server certificate and the secret encryption key
      • If set to true, the web server sessions are stored in the database. This can be useful in situations where you have multiple Connect servers (connecting to the same database) clustered behind a load balancer
      • A comma-separated list of JVM command-line options to place in the .vmoptions file
    10. DELAY
      • This tells the entrypoint script to wait for a certain amount of time (in seconds). The entrypoint script will automatically use a command-line SQL client to check connectivity and wait until the database is up before starting Connect, but only when using PostgreSQL or MySQL. If you are using Oracle or SQL Server and the database is being started up at the same time as Connect, you may want to use this option to tell Connect to wait a bit to allow the database time to startup
    To start a Connect container using one or more environment variables you use the -e parameter. For instance, to specify what type of database to use and set a VM option you could do the following:

    docker run --name connect -e DATABASE='derby' -e VMOPTIONS='-Xmx512m' -p 8443:8443 nextgenhealthcare/connect
    Most of the environment variables offer an easy way to get custom properties into Connect server’s file. As you may know, there are a ton of optional properties that can go into this file (For a full list, search the User Guide for “”), so how do you configure all of the others? We added a system that allows you to add any arbitrary property. To do this you would use a special environment variable syntax where you start with _MP_ then replace - with _ then replace . with __. Here’s an example of how to add the property database-readonly.max-connections = 25:

    docker run --name connect -e _MP_DATABASE__READONLY_MAX__CONNECTIONS='25' -p 8443:8443 nextgenhealthcare/connect
    Adding all of your environment variables as command line arguments can get pretty tedious and verbose but Docker supports loading environment variables from a file.

    Here’s an example file (be sure to substitute serverip with the correct IP):


    And Docker using the file:

    docker run --env-file=myenvfile.txt -p 8443:8443 nextgenhealthcare/connect
    Docker Secrets

    Click image for larger version  Name:	ArticleConnectDocker_Secret.jpg Views:	0 Size:	182.9 KB ID:	175106

    You may have noticed that we are passing usernames and passwords as Docker parameters in the command line. There is a more secure way of doing this using Docker Secrets. Docker Secrets are encrypted during transit and at rest in a Docker Swarm and Secrets are only accessible to services that have been granted explicit access and only while running. Docker secrets can be used in Docker Swarm, Docker Compose, and Docker Stack. The Connect Docker images support the two secret names: mirth_properties and mcserver_vmoptions. Properties in the mirth_properties secret will be merged into the container’s file and VM options in the mcserver_vmoptions secret will be added to the container’s mcserver.vmoptions file. The following example shows how to use Docker Compose to bring up Connect with a mirth_properties secret.

    First create a secret file:

    Now define your stack in a YAML file (be sure to edit the path to the file on your file system):


    version: '3.1'
        image: nextgenhealthcare/connect
        container_name: connect
          - mirth_properties
          - 8080:8080/tcp
          - 8443:8443/tcp
        file: /local/path/to/
    With your two files created you can now use Docker Compose to deploy:

    docker-compose -f mirth_stack.yml -d up
    Once Connect has started in the container you can see that the secret properties have been merged by running:

    docker exec -it connect cat conf/
    To bring down the stack:

    docker-compose -f mirth_stack.yml down

    Docker Volumes

    Click image for larger version  Name:	ArticleConnectDocker_Volume.jpg Views:	0 Size:	64.0 KB ID:	175045

    Docker volumes give users an easy way to transfer data to and from a Docker container and the host OS.

    Persisting Data with Volumes

    Specifying a volume links a local folder on your machine with a folder inside of the container. The Docker container can read and write to that local folder and the folder continues to exist outside of Docker. This example shows how to mount Connect’s appdata folder:

    docker run -v /local/path/to/appdata:/opt/connect/appdata -p 8443:8443 nextgenhealthcare/connect
    Now, with the appdata folder mounted, anything that Connect writes to the folder (The Derby database and Java keystore) will show up in your local appdata folder and you can remove your container without losing your data. This also makes updating Connect to a new version a snap. Just stop your container, remove it, and spin up a new one pointing at the same local appdata folder.

    Adding Custom Extensions with Volumes

    Connect power users will know that NextGen Connect has a plugin system allowing users to extend and add new functionality to the application. One of the official free extensions is for FHIR (Fast Healthcare Interoperability Resources) which adds source and destination connectors for the FHIR spec. NextGen has many other useful plugins available for its customers as well. Normally, to install an extension you would either stop the connect server, unzip the archive into the extensions folder, and restart it or use the Connect Administrator to upload your zip to the Connect server and restart it. With Connect running inside a Docker container with a separate and ephemeral file system, extensions must be installed differently. But, with Connect supporting an extension volume, it’s really easy!

    Create a folder on your local filesystem and drop your extension archives into that folder.

    └── local
        └── path
            └── to
                └── custom-extensions
    Then, when you start connect, be sure to mount that folder to the custom-extensions volume as part of Docker’s parameters. When the container starts up it will extract the archives into Connect’s extensions folder before starting the server, thus ensuring the extensions are installed:

    docker run -v /local/path/to/custom-extensions:/opt/connect/custom-extensions -p 8443:8443 nextgenhealthcare/connect
    Using Docker to Start Connect and a PostgreSQL Database

    If you have made it this far then you are already familiar with Docker Volumes, Docker Compose, Docker Secrets, and Docker Environment Variables. This last section will bring all of those together as well as bring a new database into the mix. Here we will compose NextGen Connect, PostgreSQL, some volumes, and secrets.

    First create a secret for Connect’s secret properties:

    Next create two secret files for PostgreSQL’s secrets:



    Then create the compose file (again, don’t forget to edit the file locations of the secret files and volumes for your local filesystem):


    version: '3.1'
        image: nextgenhealthcare/connect
        container_name: connect
          - DATABASE=postgres
          - DATABASE_URL=jdbc:postgresql://db:5432/mirthdb
          - VMOPTIONS=-Xmx512m
          - mirth_properties
          - /local/path/to/appdata:/opt/connect/appdata
          - 8080:8080/tcp
          - 8443:8443/tcp
          - db
        image: postgres
        container_name: pgsql
          - POSTGRES_DB=mirthdb
          - POSTGRES_USER_FILE=/run/secrets/postgres-user
          - POSTGRES_PASSWORD_FILE=/run/secrets/postgres-password
          - postgres-user
          - postgres-password
          - /local/path/to/pgsql_volume:/var/lib/postgresql/data
          - 5432
        file: /local/path/to/
        file: /local/path/to/pgsql_user.txt
        file: /local/path/to/pgsql_pw.txt
    Now we have everything we need to bring up the containers:

    docker-compose -f mirth_uber_stack.yml up -d
    You should see two containers running connect and pgsql.

    Further Discussion

    Check out the Connect Docker GitHub repository to see more examples of interesting ways to use our Docker images or to discuss feature requests.


    Let us know what you think about Connect Docker. Does it make your life easier? Are you using it in production? Is there something you wish it did that it isn’t yet? Leave us a comment!
      Posting comments is disabled.





    Latest Articles


    • Using Attachments
      by cturczynskyj

      Attachments are a way to optimize how Connect handles large messages.

      Using Attachments reduces the amount of data being stored in the database. If you look at a message in the message browser you can see that in the raw, transformed, and encoded tabs there are message blobs being displayed. Each one of those represents an entry in the database. Using message attachments, you can reduce the amount of data being stored substantially since, generally, attachments only need...
      07-24-2020, 04:01 PM
    • Using Connect With Docker
      by cturczynskyj

      ​We’re proud to announce that NextGen Connect is now available for use on Docker Hub!

      In the past, NextGen Connect has been available to install and run locally in Windows, Linux, Mac OSX, and our hard and soft Appliance solutions. The developers at NextGen evaluate and use a variety of tools when updating, testing, and debugging Connect. We’ve actually been using Docker for testing Connect for about a year and have found it very convenient and we hope others...
      07-23-2020, 08:45 AM