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 theedi-license.txt
license file toetc
. 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 theedi-license.bin
license file toetc
. 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.