EDI API Server Installation

Overview

The API server installation involves “pulling” and running its docker container from our Docker registry.

The API server consists of only one container, it does not need 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 as a service directly. The API Server is a Java/SpringBoot application, so you will need to install Java and configure running the API Server as a service.

Installing and Running API Server with Docker

On Linux you may need to run sudo for all docker commands.

We recommend using docker compose to run the EDI converter container; you can also run it without docker compose as explained below.

  • 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 license file to etc. You can request your trial license here.
  • Run docker compose pull. This will ensure that you have the latest image.
  • Run docker compose up -d.

On Linux/macOS:

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

You can also specify your license as an environment variable; in this case, you don’t need the etc volume.

The default port for the container is 5080, you can change it in docker-compose.yml.

To stop the service, run docker compose down.

To view the logs, run docker compose logs -f

If you prefer not to use docker compose, you can run the container directly using the steps below.

Create the etc folder and copy your license file into this folder. After that run the following commands:

docker pull repo.datainsight.health/ediconvert:2.11
docker create --name ediconvert  -p "5080:5080" -v ./etc:/app/etc repo.datainsight.health/ediconvert:2.11

To start/stop the container:

docker start ediconvert
docker stop ediconvert

To view logs:

docker logs ediconvert

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’s version by running 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 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/command line window open. To install the API server as a daemon/service, follow the instructions here.

License Key as Environment Variable

You can specify your license key using the LICENSE_KEY environment variable instead of using the license key file. This obviates the need for persistent volumes and makes deployment to Kubernetes easier to manage.

Let us know by emailing to ediconvert@datainsight.health that this is your preferred license format.

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 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