BridgeLink Quick Start Guide Docker

About This Guide

BridgeLink is Innovar Healthcare's integration platform. It moves messages between the systems in your organization and lets you build, run and watch those connections, called channels, from a web browser.

The steps here take one Linux host running Docker from an empty folder to a running BridgeLink 26.9.0 server, its database and WebAdmin.

An image is a packaged copy of a program and everything it needs to run. A container is one running copy of an image. Docker Compose starts several containers together from one settings file.

If you would like a hand with any part of the install, Innovar Healthcare's professional services team can help with as much or as little of it as you want.

What You Run

Open port 8443 on the BridgeLink server to other machines only if WebAdmin runs on another machine or other programs call the BridgeLink API. Channels that listen for connections, such as MLLP or HTTP listeners, need their own ports opened. Port 8080 is BridgeLink's plain-HTTP port; nothing in this guide uses it, so keep it closed to other machines.

The Compose file in Setting Up the Deployment already publishes 8443 on every interface of the Docker host, and Docker-published ports bypass host firewalls such as ufw. WebAdmin reaches BridgeLink over the Docker network and does not need it. To keep 8443 local to the Docker host, change "8443:8443" to "127.0.0.1:8443:8443", and use localhost in step 9 of Replace the BridgeLink Server Certificate. A channel that listens for connections also needs its port added under ports: for bl.

With Docker there is no installer to run and no archive to unpack: each image already holds the software and everything it needs. Your choices are which image variant to use and the settings you pass in.

Requirements

• A Linux host, on linux/amd64 or linux/arm64, with Docker Engine and the Docker Compose plugin. The plugin is version 2 of Compose, which you run as docker compose (with a space, not docker-compose). To install both, follow Docker's instructions at https://docs.docker.com/engine/install/.
• Permission to run docker commands. See Run Docker Without Root below.
• Internet access to Docker Hub, where the BridgeLink images are published
• sudo rights on the host, to set folder ownership
• To replace the BridgeLink server certificate (Replacing the Certificates): keytool from a Java 17 or 21 runtime on the host
• A current browser for WebAdmin: Chrome, Edge or Firefox 120 or later, or Safari 17 or later

Run Docker Without Root

On a new Linux host, the first docker command fails with permission denied while trying to connect to the docker API at unix:///var/run/docker.sock. Your account is not allowed to use Docker yet. You have two ways to fix that:

• Add your account to the docker group, then sign out and sign back in so the change takes effect
• Put sudo in front of every docker command in this guide

To add your account to the docker group, run this in a terminal on the Linux host:

sudo usermod -aG docker $USER

Getting the Images

BridgeLink server images are on Docker Hub, in the innovarhealthcare/bridgelink repository. You can pull them without signing in to Docker Hub.

Choose an Image Variant

Each variant is a tag of the same repository:

Each tag also has a Java 17 form with -jdk17 added at the end, such as 26.9.0-jdk17, 26.9.0-dhi-jdk17 and 26.9.0-dhi-slim-jdk17. Unless you need Java 17, use the tags in the table.

The two hardened images run BridgeLink the same way as the standard one. They differ in the base system, the user ID (65532), having no shell, and writing MP_ values literally; the slim image also leaves out the Administrator client. The examples in this guide use the standard image. The Container Account lists the two changes for a hardened image.

Pull the Image

docker pull innovarhealthcare/bridgelink:26.9.0

Setting Up the Deployment

Everything lives in one folder on the host: a Compose file and the appdata folder BridgeLink keeps its keystore and server ID in.

1. Create the folder:

mkdir bridgelink

2. Go into it:

cd bridgelink

3. Create the appdata folder:

mkdir appdata

4. Give it to the container's user, ID 1000 for the standard image:

sudo chown 1000:1000 appdata

5. Read the WebAdmin license terms: the Business Source License 1.1 and the BridgeLink WebAdmin Supplemental Terms. To read them without starting WebAdmin:

docker run --rm --entrypoint cat innovarhealthcare/bridgelink-webadmin:26.9.0 \
  /app/LICENSE /app/SUPPLEMENTAL-TERMS.md

6. To accept them, create a file named .env in the bridgelink folder with this one line. Compose reads it every time, so WebAdmin starts on every later command too:

echo BL_ACCEPT_LICENSE=1 > .env

7. In the bridgelink folder, create a file named docker-compose.yml with the content below, for example with nano docker-compose.yml.

YAML depends on its indentation. If you are reading the PDF, do not copy the content from it: the copy loses the indentation and picks up page headers and footers. Copy it from the HTML version of this guide instead, or use the docker-compose.yml file that comes with this guide.

services:
  bl:
    image: innovarhealthcare/bridgelink:26.9.0
    user: "1000:1000"
    ports:
      - "8443:8443"
    volumes:
      - ./appdata:/opt/bridgelink/appdata
    environment:
      MP_DATABASE: postgres
      MP_DATABASE_URL: jdbc:postgresql://postgres:5432/bridgelinkdb
      MP_DATABASE_USERNAME: bridgelink
      MP_DATABASE_PASSWORD: change-me-database
      MP_KEYSTORE_STOREPASS: change-me-store
      MP_KEYSTORE_KEYPASS: change-me-key
    security_opt:
      - no-new-privileges:true
    stop_grace_period: 35s
    depends_on:
      - postgres
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: bridgelinkdb
      POSTGRES_USER: bridgelink
      POSTGRES_PASSWORD: change-me-database
    volumes:
      - pgdata:/var/lib/postgresql/data
    restart: unless-stopped

  webadmin:
    image: innovarhealthcare/bridgelink-webadmin:26.9.0
    ports:
      - "8444:8444"
    environment:
      PORT: "8444"
      NODE_ENV: production
      BRIDGELINK_SERVER_URL: https://bl:8443
      BL_ACCEPT_LICENSE: ${BL_ACCEPT_LICENSE:-}
    volumes:
      - webadmin-certs:/app/certs
    security_opt:
      - no-new-privileges:true
    depends_on:
      bl:
        condition: service_healthy
    restart: unless-stopped

volumes:
  pgdata:
  webadmin-certs:

8. In docker-compose.yml, replace each change-me-... value with a password of your own. Follow these rules:
   • Replace the whole value, including its -database, -store or -key ending
   • Use letters and digits only. Compose treats a $ as the start of a variable. With the standard image, a | in MP_DATABASE_PASSWORD cannot be written, so BridgeLink starts with an empty database password, cannot sign in to the database, and restarts again and again (see Troubleshooting). A backslash is unsafe in every password with both images, because BridgeLink reads mirth.properties with backslash as an escape character.
   • Use one password for the database and a different one for each keystore value
   • Under bl:, set MP_DATABASE_PASSWORD, MP_KEYSTORE_STOREPASS and MP_KEYSTORE_KEYPASS
   • Under postgres:, set POSTGRES_PASSWORD to the same value as MP_DATABASE_PASSWORD

What the settings do:

Run every docker compose command in this guide from the bridgelink folder. From any other folder, the commands fail with no configuration file provided: not found.

Choosing and Connecting the Database

Every BridgeLink server keeps its channels, messages, events, users and settings in one database. BridgeLink reads that choice from its settings file, conf/mirth.properties. In a container you set those settings with environment variables, and the container writes them into mirth.properties each time it starts.

Always Use an External Database in a Container

BridgeLink ships set to the default Derby database. Do not use it in a container:

• Cannot run on the -jdk17 tags. BridgeLink 26.9 will not start a server on the default Derby database with any Java older than 21. The standard images use Java 21, but the tags ending in -jdk17 do not, and on those the server stops at once and logs embedded Derby requires Java 21+ as of 26.9; upgrade Java or switch to an external database.
• Runs inside BridgeLink. Derby lives in the same process as the server, so no other tool can open the database while BridgeLink runs, and its files would have to live in a volume and be backed up by copying.
• Lacks features. The default Derby database does not support the JSON value type in Lookup Manager or regex search in Message Browser. SQL Server does not support regex search either.
• Sized for evaluation. For production message volumes, use PostgreSQL, MySQL, Microsoft SQL Server or Oracle.

The Compose file in Setting Up the Deployment runs PostgreSQL next to BridgeLink. To use a database server you already run, delete the postgres service and point the variables below at your server.

The Database Variables

For an existing database server, first create an empty database for BridgeLink and a login that owns it and can create tables. BridgeLink creates all of its tables the first time it starts.

Setting Any Other Property

Any variable that starts with MP_ sets the matching line in mirth.properties. Drop the MP_ prefix, turn each __ into -, turn each remaining _ into ., and change every letter to lowercase. For example, MP_DATABASE__READONLY_MAX__CONNECTIONS sets database-readonly.max-connections.

Because the name is lowercased, you cannot set a property whose name has a capital letter this way. The one exception is MP_SERVER_ALLOWROOT.

Two other variables do not follow this rule. MP_VMOPTIONS writes the vmoptions file rather than a line in mirth.properties, as Memory for the BridgeLink Server describes, and MP_DATABASE_RETRY_WAIT sets database.connection.retrywaitinmilliseconds, the wait in milliseconds between database connection attempts at startup.

The Container Account

In a container, BridgeLink runs as the user the container runs as. That user decides what BridgeLink can write to, the job a service account does on a server.

Why Not Root

Channels can run scripts. If BridgeLink runs as root, any script in any channel has full control of the container. So BridgeLink refuses to start as root by default, and the log shows:

ERROR: BridgeLink is running as root/Administrator.

The BridgeLink images already run as a non-root user:

Keep the user: line in the Compose file matched to your image, and never set it to root or 0.

Any host folder you mount into the BridgeLink container, such as appdata, must belong to that user ID so BridgeLink can write to it.

Using a Hardened Image

Make these two changes to Setting Up the Deployment:

1. Give appdata to user ID 65532 instead of 1000:

sudo chown -R 65532:65532 appdata

2. In docker-compose.yml, change the image: and user: lines under bl: so they read:

services:
  bl:
    image: innovarhealthcare/bridgelink:26.9.0-dhi
    user: "65532:65532"

A hardened container has no shell and no command-line tools, so docker compose exec bl sh fails with executable file not found. To check a hardened container, read its log with docker compose logs bl and look at the files in appdata on the host.

Changing the User After Setup

Suppose the deployment ran with one image and you switch to the other, or you change the user: line. The files in appdata still belong to the old user ID. The new user cannot write the keystore or its other files, and BridgeLink fails with Permission denied errors.

1. Stop BridgeLink:

docker compose stop bl

2. Give appdata to the new user ID, for example 65532:

sudo chown -R 65532:65532 appdata

3. In docker-compose.yml, change the image: and user: lines under bl: to the new image and user ID. For the hardened image, they read:

services:
  bl:
    image: innovarhealthcare/bridgelink:26.9.0-dhi
    user: "65532:65532"

4. Give the new user ID the same access to any other host folders you mount for your channels.
5. Start BridgeLink with the new settings:

docker compose up -d bl

Starting BridgeLink for the First Time

1. From the bridgelink folder, start everything:

docker compose up -d

docker compose up -d does not return until bl reports healthy, because WebAdmin waits for it. On a normal start that takes about a minute or less. If the command has not returned after a couple of minutes, open a second terminal in the bridgelink folder, run step 2 to see what bl is doing, and see Troubleshooting.

2. Follow the BridgeLink log:

docker compose logs -f bl

3. Wait for the newest line that contains Web server running at, with a time after the start you just made. That line is the sign that BridgeLink started. Each log line begins with the container name, the log level and a time, so look for the text anywhere in the line.
4. Find the newest line that contains Running, to check the database name and Java version. Confirm it shows postgres, not derby.
5. Press Control-C to stop following the log. The containers keep running.
6. Check the containers:

docker compose ps

The bl container reports healthy once BridgeLink has started and finished deploying its channels. A first start can take longer on a slow host or a host that is busy with other work.

A Running line on its own does not mean BridgeLink started. If the keystore cannot be opened, or appdata cannot be written, the log still shows Running, but it never shows Web server running at, and port 8443 refuses connections. See Troubleshooting.

On this first start, BridgeLink:

• Creates its tables in the database
• Creates a keystore in appdata holding a new self-signed certificate for port 8443
• Creates appdata/server.id, which holds this server's unique ID

If PostgreSQL is still starting when BridgeLink first tries it, BridgeLink retries twice, 10 seconds apart, then stops. restart: unless-stopped starts it again, so give it a minute before you look for a problem.

Memory for the BridgeLink Server

BridgeLink starts with a 256 MB Java heap, which is enough for a personal or test install but small for production. The release's blserver.vmoptions sets it.

To change it, add MP_VMOPTIONS at the end of the environment: section under bl: in docker-compose.yml. A bare number sets the heap in MB:

services:
  bl:
    environment:
      MP_KEYSTORE_KEYPASS: your-keystore-key-password
      MP_VMOPTIONS: "1024"

Leave memory for the host and for the database. If you give the container a memory limit, the limit must be larger than the heap. To apply the change, run this from the bridgelink folder:

docker compose up -d bl

Running WebAdmin

WebAdmin is the browser-based tool you use to manage BridgeLink. In Docker it is always a separate container: no BridgeLink image includes it. The Compose file in Setting Up the Deployment already runs it.

The WebAdmin Container

WebAdmin reaches BridgeLink over the Docker network by the service name bl.

Sign In for the First Time

1. Open https://your-docker-host:8444 in a browser.
2. If the browser shows a certificate warning, click Advanced, then Proceed to ... (unsafe) in Chrome or Continue to ... (unsafe) in Edge. In Firefox, click Advanced, then Accept the Risk and Continue. Read the note after this step.

3. In Username, type admin.
4. In Password, type admin.
5. Click Login.
6. On Welcome to BridgeLink, leave Username as admin.
7. In New Password, type a new password of at least 8 characters, with an uppercase letter, a lowercase letter, a number, and a special character such as !, @, #, $, % or *. A hyphen, period or space does not count as a special character, and the password cannot be admin. WebAdmin lists only the rules that admin breaks, so check your password against all of these.
8. Type it again in Confirm Password.
9. The profile fields on Welcome to BridgeLink are optional; fill them in if you want to.
10. Click Save & Continue.

Controlling the WebAdmin Container

WebAdmin runs in its own container, so you control it with Docker Compose from the bridgelink folder. WebAdmin's errors go to its container log:

docker compose logs webadmin

To restart WebAdmin:

docker compose restart webadmin

More WebAdmin Setups

For WebAdmin outside Docker, one WebAdmin for several servers, your own certificate, and every setting, see the BridgeLink WebAdmin Setup Guide on the BridgeLink download page, https://www.bridgelink.net/download.

Finding the Server ID

Every BridgeLink server has a unique server ID, created the first time it starts. Plugin licenses are issued against this ID, so Innovar Healthcare asks for it when you license a plugin.

In WebAdmin

1. Sign in to WebAdmin.
2. In the left sidebar, scroll to the bottom and, under Help, click About BridgeLink.

If Update Available opens instead, click Got it, then click About BridgeLink again.

3. Click the copy icon beside Server ID.

On the Host

The same ID is in the appdata folder you mounted:

sudo cat appdata/server.id

The file holds one line in the form server.id = <ID>. The ID is the part after the equals sign.

Back up the whole appdata folder together with your docker-compose.yml (and .env, if you use one). Besides server.id and keystore.jks, appdata holds the Configuration Map. The keystore holds the key BridgeLink uses to encrypt data, and the Compose file holds the keystore passwords. The database is separate: channels, users, settings and messages live in the pgdata volume, so back up the database too, for example with pg_dump. If you use the mirth_properties secret, back up that file as well. Settings changed at runtime in mirth.properties are lost when the container is recreated; set them with MP_ variables instead.

Keep the ID Fixed

A container is easy to replace, and a replaced container without its appdata folder would get a new ID. To make sure the ID never changes, set it in the Compose file once you have it:

1. Copy the ID from About BridgeLink.
2. In docker-compose.yml, find the bl: service and the environment: section inside it, the one with the MP_ lines. Add this line at the end of that section, lined up with the MP_ lines, with your ID in place of your-server-id. Keep the indentation exactly as shown, because YAML depends on it:

services:
  bl:
    environment:
      MP_KEYSTORE_KEYPASS: your-keystore-key-password
      SERVER_ID: your-server-id

3. Apply the change, from the bridgelink folder:

docker compose up -d bl

The container writes this ID into appdata/server.id every time it starts.

Replacing the Certificates

A new deployment uses two self-signed certificates (certificates the server creates for itself, which browsers do not trust), which is why browsers warn the first time. Before you use BridgeLink in production, replace them with certificates from your organization's certificate authority (CA).

This chapter has two separate procedures, one for each certificate. Each has its own numbered steps, and you do not need to do one to do the other.

Replace the WebAdmin Certificate

Before you replace WebAdmin's certificate, read When a browser stops letting you click through under Sign In for the First Time in Running WebAdmin.

You need the certificate and its private key as PEM files (text files that begin with -----BEGIN). The certificate must be one that users' browsers trust, and it must name the address they type to reach WebAdmin. Put any intermediate certificates in the certificate file after the server certificate. The private key file must not have a password.

1. Create a folder on the host for them:

sudo mkdir -p /etc/ssl/bridgelink-webadmin

2. Copy your certificate into it as server.crt. Replace /path/to/your-certificate.pem with the path to your own certificate file:

sudo cp /path/to/your-certificate.pem /etc/ssl/bridgelink-webadmin/server.crt

3. Copy your private key into it as server.key. Replace /path/to/your-private-key.pem with the path to your own key file:

sudo cp /path/to/your-private-key.pem /etc/ssl/bridgelink-webadmin/server.key

4. Give the folder to the WebAdmin container's user, ID 1000:

sudo chown -R 1000:1000 /etc/ssl/bridgelink-webadmin

5. Make the private key readable only by its owner:

sudo chmod 600 /etc/ssl/bridgelink-webadmin/server.key

6. In docker-compose.yml, find the webadmin: service. Replace its existing - webadmin-certs:/app/certs line with the line below, and leave the other volumes: sections as they are. Include the - at the start of the line, because it is part of the file. Keep the indentation exactly as shown, because YAML depends on it:

  webadmin:
    volumes:
      - /etc/ssl/bridgelink-webadmin:/app/certs:ro

7. Recreate the WebAdmin container, from the bridgelink folder:

docker compose up -d webadmin

8. Open WebAdmin in a browser and confirm there is no certificate warning.

To Undo the Swap

If browsers cannot open WebAdmin after the swap, put the old certificate back:

1. In docker-compose.yml, put the - webadmin-certs:/app/certs line back in place of the line you added in step 6.
2. Recreate the WebAdmin container, from the bridgelink folder:

docker compose up -d webadmin

The original certificate returns from the webadmin-certs volume.

Browsers that opened WebAdmin by its server name with the new certificate refuse the old self-signed one. Fix the new certificate instead, or clear the browser's HSTS entry for the server name: open chrome://net-internals/#hsts in Chrome or edge://net-internals/#hsts in Edge, and use Delete domain security policies. In other browsers, clear the browsing data for that server name.

Replace the BridgeLink Server Certificate

BridgeLink keeps its certificate in a keystore file under the name mirthconnect. The same keystore also holds the key BridgeLink uses to encrypt data, so replace only the mirthconnect entry. Never swap in a different keystore file.

You need the certificate and private key as a PKCS12 file (a single file, ending in .p12 or .pfx, that bundles a certificate with its private key) and its password, plus keytool on the host, which comes with any Java 17 or 21 install.

The commands below contain placeholders in angle brackets. Replace each one, including the angle brackets, with your own value:

1. Stop BridgeLink:

docker compose stop bl

2. Back up the keystore:

sudo cp appdata/keystore.jks keystore.jks.bak

3. Copy your PKCS12 file into the bridgelink folder as server.p12. The commands that follow run from that folder and expect the file there.
4. List the entry name inside your PKCS12 file:

keytool -list -keystore server.p12 -storetype PKCS12

5. Remove the old certificate entry:

sudo keytool -delete -alias mirthconnect -keystore appdata/keystore.jks \
  -storetype JCEKS -storepass <your MP_KEYSTORE_STOREPASS value>

6. Import yours as mirthconnect:

sudo keytool -importkeystore -srckeystore server.p12 -srcstoretype PKCS12 \
  -srcstorepass <your .p12 file password> \
  -srcalias <the entry name from step 4> \
  -destkeystore appdata/keystore.jks -deststoretype JCEKS \
  -deststorepass <your MP_KEYSTORE_STOREPASS value> -destalias mirthconnect \
  -destkeypass <your MP_KEYSTORE_KEYPASS value>

Steps 5 and 6 print a warning that recommends migrating the keystore to PKCS12. Ignore it: BridgeLink reads the keystore as JCEKS, so do not convert it.

7. Give the keystore back to the container's user, ID 1000 for the standard image:

sudo chown 1000:1000 appdata/keystore.jks

For a hardened image, which runs as user 65532, run this instead:

sudo chown 65532:65532 appdata/keystore.jks

8. Start BridgeLink:

docker compose start bl

9. Open https://your-docker-host:8443 in a browser and confirm the browser shows your certificate.

If BridgeLink does not start, or port 8443 does not answer: stop BridgeLink, copy the backup keystore.jks.bak you made in step 2 back to appdata/keystore.jks, repeat the chown from step 7, and start BridgeLink.

WebAdmin keeps working through the change, with no change to its own settings.

The Data Pruner

BridgeLink keeps the messages each channel processes until the Data Pruner removes them. The Data Pruner is off on a new server, so turn it on before you send real traffic through BridgeLink; otherwise the database grows with every message.

It has two parts, and both have to be set:

• The schedule, for the whole server: in WebAdmin, in the left sidebar under Administration, click Settings, then the Data Pruner tab
• How long each channel keeps messages: on each channel's Summary tab, under Message Pruning. A channel whose pruning fields are blank is never pruned, even when the schedule is on.

Choose ages that match your organization's record-keeping rules.

Turn On the Schedule

1. In WebAdmin, in the left sidebar under Administration, click Settings.
2. Click the Data Pruner tab.
3. Under Schedule, set Enable to Yes.
4. Choose a Schedule Type and set when it runs: Interval runs every set number of hours or minutes, Time runs once a day, and Cron takes cron expressions. Once a day at a quiet hour suits most servers.
5. Click Save.

Set How Long Each Channel Keeps Messages

1. In the left sidebar under Build, click Channels.
2. Double-click the channel to open it in the channel editor.
3. On the Summary tab, under Message Pruning, enter the number of days in Prune metadata after and Prune content after. Content cannot be kept longer than metadata.
4. Click Save.
5. Repeat for each channel.

Incomplete and queued messages are never pruned. Errored messages are kept too, unless you check Prune errored messages.

Troubleshooting

For more WebAdmin problems, see Troubleshooting in the BridgeLink WebAdmin Setup Guide.

Support

Customers with an active Innovar Healthcare support plan can contact support at support@innovarhealthcare.com. Include the BridgeLink image and tag (or digest), your Compose file with the passwords removed, what you were doing, and the most recent part of docker compose logs bl. docker compose logs bl can contain message content, which may include patient data. Remove patient data before you send a log, or ask support for a secure way to send it.