Quick start | HL7 Edge Gateway

From download to first ACK

1
Download the gateway.
Sign in at lambogenius.com (a free account is enough) and open Downloads. Pick the binary for your operating system, or the Docker image, and check its SHA-256 against the one shown on the page. The Docker image is also signed: see Verify the Docker image.

Write a config file.

Copy hl7-edge-gateway.example.toml to hl7-edge-gateway.toml and set your routes. ${NAME} is replaced with the environment variable NAME, so secrets stay out of the file.

[admin]
listen = "127.0.0.1:8080"
# token = "${HL7EDGE_ADMIN_TOKEN}"   # required when listen is not a loopback address

[store]
backend = "embedded"
path = "data"
dedup_window = "2m"

# MEDITECH → MLLP → an HTTPS API, queued
[[route]]
name = "lab-oru"
mode = "store_and_forward"
source = { type = "mllp", listen = "10.10.10.10:7890" }
destination = { type = "http", url = "https://somewhere.com/lab/oru", headers = { Authorization = "Bearer ${LAB_API_TOKEN}" } }

[route.store_and_forward]
on_reject = "dead_letter"
retry = { initial = "1s", max = "5m", multiplier = 2.0 }

# MEDITECH → MLLP → an HTTPS API, answering with its result
[[route]]
name = "lab-adt"
mode = "passthrough"
source = { type = "mllp", listen = "10.10.10.10:7891" }
destination = { type = "http", url = "https://somewhere.com/lab/adt", headers = { Authorization = "Bearer ${LAB_API_TOKEN}" } }

[route.passthrough]
ack_from = "response_body"
on_error = "AE"

Check it and run the gateway.

A developer license is enough for test messages (MSH-11 = T). Set LAMBOGENIUS_LICENSE first, or install the token from the console at http://127.0.0.1:8080.

hl7-edge-gateway check -c hl7-edge-gateway.toml
hl7-edge-gateway run   -c hl7-edge-gateway.toml

# In another terminal: send a test message and print the ACK
hl7-edge-gateway send --to 127.0.0.1:7890 samples/oru-r01.hl7

4
Point the sending system at the gateway.
In MEDITECH, or any other sender, set the outbound interface's host and port to the route source's listen address. Watch messages arrive on the route in the console.

With Docker, load the image you downloaded. Its built-in configuration has two routes: lab-oru on port 7890 (store-and-forward) and lab-adt on 7891 (pass-through), with the console on 8080. Keep the queue on a volume. To use your own routes, mount your file at /etc/hl7-edge-gateway/hl7-edge-gateway.toml, with 0.0.0.0 listen addresses.

docker load -i hl7-edge-gateway-<version>-docker-image-linux-amd64.tar.gz

docker run -d --name hl7-edge-gateway \
  -p 7890:7890 -p 7891:7891 -p 8080:8080 \
  -v hl7edge-data:/var/lib/hl7-edge-gateway \
  -e LAMBOGENIUS_LICENSE="<your license token>" \
  -e HL7EDGE_ADMIN_TOKEN="<a long random token>" \
  -e LAB_ORU_URL="https://somewhere.com/lab/oru" \
  -e LAB_ADT_URL="https://somewhere.com/lab/adt" \
  lambogenius/hl7-edge-gateway:<version>

Verify the Docker image

The Docker image archive is signed with cosign. Download its .cosign.bundle from the same release, save the Lambogenius public key below as cosign.pub, and check the archive before docker load. Any other result than Verified OK means the file isn't the one Lambogenius published: don't load it.

-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEbQ70j4nc5SEW6iwU8Mz0aW4mMP2J
KmUxR419zB5Q6Xif99LXSpQoDQUXtsdIAObsHV2j/yyhLd6x/fkXhyMjFA==
-----END PUBLIC KEY-----

cosign verify-blob --key cosign.pub \
  --bundle hl7-edge-gateway-<version>-docker-image-linux-amd64.tar.gz.cosign.bundle \
  hl7-edge-gateway-<version>-docker-image-linux-amd64.tar.gz
# Verified OK

# Without cosign installed, run it from its image:
docker run --rm -v "$PWD:/w" -w /w gcr.io/projectsigstore/cosign:v2.4.1 verify-blob --key cosign.pub \
  --bundle hl7-edge-gateway-<version>-docker-image-linux-amd64.tar.gz.cosign.bundle \
  hl7-edge-gateway-<version>-docker-image-linux-amd64.tar.gz

Next: choose a delivery mode for each route, add HTTP, SOAP or MLLP endpoints, and turn on TLS.