EDI API Server Installation

Overview

The API server runs in a single Docker container and does not require a database. The container is completely stateless; you don’t need to create and manage volumes.

This makes it easy to run multiple instances of the API Server and scale it up/down depending on your workload.

If you prefer not to use Docker, you can install the API Server directly on your machine. The API Server is a Java/SpringBoot application, so you will need to install Java and configure it to run the API Server as a service.

You will need a license key to run the API server. You can request your trial license here.

Installing and Running API Server with Docker

Docker Command Line

Create the “etc” folder and save the license key file (edi-license.txt) there.

Pull the latest image:

docker pull repo.datainsight.health/ediconvert:2.14

Create the container:

docker rm -f ediconvert 2>/dev/null || true
docker create --name ediconvert  -p "5080:5080" --restart unless-stopped \
-v <path to your etc folder>:/app/etc:ro repo.datainsight.health/ediconvert:2.14

Alternatively, open your license key file (edi-license.txt) and use the entire content of that file as the value for the LICENSE_KEY variable. Using the license key variable is recommended if you want a fully stateless container (e.g., for deployment to Kubernetes).

docker create --name ediconvert  -p "5080:5080" --restart unless-stopped \
-e LICENSE_KEY="<your_license_key>" repo.datainsight.health/ediconvert:2.14

On Linux, you need to run sudo for all Docker commands, e.g., sudo docker create ...

--restart unless-stopped ensures the container restarts automatically after reboots.

Start the container:

docker start ediconvert

It takes a few seconds for the container to start. View the logs to make sure that the server is up and running:

docker logs ediconvert -f

You should see the “Started HdiApplication” line in the logs once the server starts. The line before will contain the license information.

Run the initial smoke test to verify your installation.

To stop the container:

docker stop ediconvert

Docker Compose

  • Create a new folder (e.g., “edi”), download docker-compose.yml file from this link and copy it into this folder
  • Navigate to the folder where you saved the docker-compose.yml
  • Create the etc folder. Copy the edi-license.txt license file to etc.
  • Alternatively, create - LICENSE_KEY=<your license key> environment variable in docker-compose.yml.
  • Run docker compose pull. This will ensure that you have the latest image.
  • Run docker compose up -d.

You can run the following commands on Linux/macOS to execute the steps above:

mkdir edi
cd edi
mkdir etc
# Copy the license file from the location you downloaded it to etc
cp edi-license.txt etc
wget https://datainsight.health/edi-convert/docker-compose.yml
docker compose pull
docker compose up -d
docker compose logs

It takes a few seconds for the container to start. To make sure that the server is up and running, run docker compose logs -f and look for the line “Started HdiApplication” in the log.

Run the initial smoke test to verify your installation.

To stop the service, run docker compose down.

To view the logs, run docker compose logs -f.

Docker Environment Variables

Environment variables that you can use to configure the server:

  • LICENSE_KEY: the value of the license key.
  • codeset_enrichcodes: Set to false to disable code enrichment (adding descriptions to codes) to improve performance.
  • ediviewer_filesizelimit: The maximum size of uploaded files in bytes for EDI Viewer. See this page for more details.
  • JAVA_TOOL_OPTIONS: Java settings. Default value: “"-XX:MaxRAMPercentage=75 -XX:InitialRAMPercentage=10 -XX:+ExitOnOutOfMemoryError -Djava.io.tmpdir=/app/tmp”

Timezone Settings

The default timezone is UTC.

X12 EDI healthcare transactions do not support time zones, so the date and time you see in API responses are always in UTC.

You can change the timezone by overriding the JAVA_TOOL_OPTIONS JVM property and adding the -Duser.timezone=<your timezone> option:

docker run -e JAVA_TOOL_OPTIONS="-Duser.timezone=America/New_York -XX:MaxRAMPercentage=75 -XX:InitialRAMPercentage=10 -XX:+ExitOnOutOfMemoryError -Djava.io.tmpdir=/app/tmp"

Use the IANA Time Zone Database to find the correct value for your timezone.

Docker Mount Points

The container exposes the following mount points. You don’t need to explicitly create them unless you want to customize the server’s behavior. The only required mount point is /app/etc if you saved your license file there.

  • /app/etc: the default location for the license file and other configuration files.
  • /app/logs: the location for the server’s logs.
  • /app/upload: the location of the uploaded files, when files are uploaded via the embedded EDI Viewer.
  • /app/load: the location of the files for the embedded EDI Viewer, see here for more details.
  • /app/tmp: temporary directory; all EDI files are saved here before being converted.

The server runs in the /app directory, so your mount points can be relative to that directory.

Note that the server runs as a non-root user with the ID 10001, so you need to grant write permissions to the mounted locations that are not read-only (all of them except /app/etc).

To grant write permissions to the mounted locations, run the following command:

chown -R 10001:10001 <location on the host>

Installation without Docker

The API server is a Java application. You can install it on any server using the steps below:

  • Download and install Java. Java 17 or higher is required. We recommend using the latest long-term support release of Java. You can also install Java using sdkman or a package manager on Linux or macOS. Once you install Java, verify the Java version by running the java -version command from the terminal/command line window.
  • Create a folder/directory where you’re going to install the API back-end, e.g., edi
  • Create the etc folder inside the newly created folder. Copy the edi-license.txt license file to etc. You can request your trial license here.
  • Download the distribution’s zip file from this link
  • Unzip the zip file into the installation folder/directory (e.g., into edi)
  • Open the terminal/command line window and navigate to the installation folder/directory (cd edi)
  • Run java -jar ediconvert.war

You need to keep this terminal or command-line window open.

To install the API server as a daemon/service, follow the instructions here. You can find a sample systemd service file here.

Initial Tests to Verify the Installation

To verify that the server is running, open http://localhost:5080/api/about or run this command:

curl http://localhost:5080/api/about

You may also want to convert a test EDI file. You can find many sample files in our GitHub repo.

Download any of the files and run:

curl -H "Content-Type: text/plain" --data-binary @<your file> http://localhost:5080/api/edi/json

System Requirements

The API Server can be installed on any Linux, macOS, or Windows server with Docker preinstalled.

Here are the requirements for the host VM:

  • RAM: 4 GB, 16GB if you convert a lot of files in parallel
  • Disk space: 100 GB
  • Cores: two processor cores

Software requirements:

  • Docker Engine: 19 or higher
  • Docker Compose: 1.18 or higher

TLS/SSL Configuration

We recommend terminating TLS/SSL at the load balancer or reverse proxy in front of the API server.

If you need to run the API server over TLS/SSL, you need to specify environment variables that point to your certificate and private key.

You can save your certificate and private key using the “etc” mount point described above.

You also need to change the container’s port, e.g., -p "5443:5080".

For the key/certificate in PEM format, use the following environment variables:

  • SERVER_SSL_CERTIFICATE: path to your X.509 certificate file, e.g., ./etc/ssl/certificate.crt
  • SERVER_SSL_CERTIFICATEPRIVATEKEY: path to the file containing your private key, e.g., ./etc/ssl/private.key
  • SERVER_SSL_CERTIFICATEPRIVATEKEYPASSWORD: the key file’s password if it’s password-protected

See this Docker compose file or this shell script for an example.