Running

If you want to run evitaDB as a separate service on your server, you can use Docker. This chapter describes how to run evitaDB in Docker and how to configure it.

The Docker image is based on RedHat JDK / Linux (see ) base image (Fedora family) and is published to Docker Hub.

Install Docker

Before we get started, you need to install Docker. You can find instructions for your platform in the Docker documentation.

Pull and run image

Once Docker is installed, you need to grab the evitaDB image from Docker Hub and create a container. You can do both in one command using docker run. This is the easiest way to run evitaDB for testing purposes:

When you start the evitaDB server you should see the following information in the console output:

Argument	Description
--name	gives a container a name evitadb. if you don't give the container a name, Docker will generate a random name for it.
-i	keeps STDIN open - the container will run in the foreground, and you'll see the container's standard/error output in the console. in the console, and you can stop the container by sending it a terminal signal (usually the the key combination Ctrl+C, or Command+. on MacOS).
--rm	removes the file system (data) created by evitaDB, by using this command there will be nothing left on your system when evitaDB is stopped, this argument is especially useful for testing purposes
--net=host	instructs Docker to use directly host system network stack, this way evitaDB behaves as if it runs directly on the host system network-wise, if the port configured in evitaDB configuration is already used on the system, Evita fails to set up appropriate web API (see next chapter for port remapping or evitaDB configuration for specifying open ports)

Open / remap ports

The simplified command shares the network with the host, which is not always the best approach. You can selectively open/re-mapping ports opened inside the Docker container in the following way:

The -e "api.exposedOn=localhost" argument is necessary when evitaLab and/or Open API schema is generated and used from the host system the docker container is running on. This argument is not necessary when container shares the network with the host using argument --net=host. Argument tells evitaDB running in container to use localhost as a domain for generated URLs in the schemas and the evitaLab network requests. Otherwise it would use the container inner hostname as a domain, which is not accessible from the outer host system.

Default port	Service
5555	serves end-user GraphQL / REST APIs on /gql and /rest sub-paths
5556	serves system gRPC API
5557	provides access to the TLS/SSL certificate (see configuring TLS/SSL)

Argument	Description
-p	port remapping in the format host port:container port, so you could remap default ports opened by evitaDB inside the container to different ports on the host system.

Configure database persistent storage

For regular use, you'll probably want to specify the folder for storing evitaDB data and easily access it in the host's file system structure. You can specify any (initially) empty host folder to store the evitaDB database files:

You will need to replace __data_dir__ with the path to the folder on your host system.

The folder begins to fill with data as you create your first catalogs and collections of entities. The organisation of folder will look like this:

Each folder will contain one or more files representing the contents of the catalog.

More details about the folder structure and file contents are documented in the back-up and restore chapter.

Configure the evitaDB in the container

You can control all evitaDB settings in the container using environment variables specified in run command:

The example command above runs evitaDB and opens Java debug on port 5000. It also disables the GraphQL and gRPC web APIs and leaves only the REST API running (by default evitaDB starts all available APIs).

You can take advantage of all the following variables:

List of all configurable environment variables
Variable name	Meaning
EVITA_CONFIG_FILE	path to configuration file, default: /evita/conf/evita-configuration.yaml
EVITA_STORAGE_DIR	path to storage directory, default: /evita/data
EVITA_CERTIFICATE_DIR	path to directory with automatically generated server certificates. Default: /evita/certificates
EVITA_JAVA_OPTS	Java commandline arguments (list of basic arguments can be found here), default: none (empty string)
EVITA_ARGS	evitaDB server command-line arguments, default: none (empty string) the list of all available arguments is given in the configuration file: the format of the argument is visible in the variables ${argument_name:default_value} to pass an argument to a Java aplication, you need to prefix it with -D, the correct argument name for variable ${storage.lockTimeoutSeconds:50} is -Dstorage.lockTimeoutSeconds=90

You can also provide the entire configuration YAML file using a special volume in the following way:

You need to replace __config_file__ with the path to the YAML file and __data_dir__, __certificate_dir__ with existing folders on the host file system.

The contents should match the default configuration file , but you can specify constants instead of variables in certain settings.

Check the container status

You can check the container status by running the `docker ps' command, and you'll see similar output:

If you are using the host network stack (--net=host), you won't see any ports in the output. If you use remap/open ports you will also see the ports configuration here.

Check statuses of the APIs

You can check statuses of the GraphQL and the REST API by using the curl command.

GraphQL

For GraphQL API run (applies to default evitaDB configuration):

this should return following confirmation about liveness status of the GraphQL API:

REST

For REST API run (applies to default evitaDB configuration):

this should return following confirmation about liveness status of the REST API:

Control logging

evitaDB uses the Slf4j logging facade with Logback implementation, but you're free to change this. The default logback configuration is defined in a file .

You can completely override the default logback configuration by providing your own logback configuration file in a volume:

You need to replace __path_to_log_file__ with the path to your logback configuration file.

Restart an existing container

The running (and named) container can be stopped and restarted using the following commands:

Alternatively, you can use docker ps to get the ID of a running container and restart it using the UUID short identifier:

Docker Compose

If you want to use evitaDB in orchestration with other services or your own Dockerised application, you can evitaDB in the Docker compose file. The basic configuration could look like this:

All previously documented options for using Docker apply to Docker Compose:

use environment variables to configure evitaDB
use volumes to set the data folder
use ports for mapping ports in the docker composition

Author: Ing. Jan Novotný

Date updated: 17.1.2023

Documentation Source