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 edi-license.txt 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.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.

You can also provide your license key using 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 create --name ediconvert  -p "5080:5080" -v ./etc:/app/etc repo.datainsight.health/ediconvert:2.12

To start/stop the container:

docker start ediconvert
docker stop ediconvert

To view logs:

docker logs ediconvert -f

To make sure that the server is up and running, run docker logs ediconvert -f and look for the line “Started HdiApplication” in the log.

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 edi-license.bin 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.

Open your license key file (edi-license.txt) and copy the entire content of that file to the LICENSE_KEY variable.

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

TLS/SSL Configuration

You need to specify environment variables pointing to your certificate and private key to run the API server over TLS/SSL.

You may also want 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.