Running with Docker/Compose

If you just want to try out Horizon, one way of doing so could be to directly run Horizon from Docker. For resiliency reasons, this is obviously not recommended for production usage.

We provide a Docker image that’s entirely configurable through environment variables. All Docker examples require that you login to our Docker repository beforehand :

$ docker login registry.evertrust.io
If you’re looking to try out Horizon’s features, take a look at the EVERTRUST Playground. It is a Docker Compose project bundled with demo values to get you started swiftly.

Docker Compose example

The simplest way to spin up an Horizon instance is to let Docker Compose manage the required components :

  • the database,

  • the Horizon instance

  • and (optionally) the reverse proxy.

Copy the following docker-compose.yaml file and tweak it to match your needs :

version: "3.1"
services:
  horizon:
    image: registry.evertrust.io/horizon:2.6.x
    ports:
      - "9000:9000"
    networks:
      - horizon
    environment:
      LICENSE: MI...
      APPLICATION_SECRET: tobechanged
      EVENT_SEAL_SECRET: tobechanged
      VAULT_TYPE: ssv
      VAULT_MASTER_PASSWORD: tobechanged
      HOSTS_ALLOWED.0: .
      MONGODB_URI: mongodb://mongo:27017/horizon
    depends_on:
      - mongo
    healthcheck:
      test: [ "CMD", "curl", "-f", "http://localhost:7626/ready" ]
      interval: 10s
      timeout: 60s
      retries: 10
  mongo:
    image: mongo:5
    restart: always
    volumes:
      - database:/data/db
    networks:
      - horizon
volumes:
  database: {}
networks:
  horizon: {}

You then only need to run the following in the directory where you created the previous file :

$ docker compose up

Horizon should quickly become available on http://localhost:9000.

Vanilla Docker example

Pull the latest Horizon image:

$ docker pull registry.evertrust.io/horizon:2.6.x

The Horizon Docker image ships with sensible configuration defaults. Most can be configured by injecting environment variables when running the container, like so:

$ docker run \ -e LICENSE="MI…​" -e APPLICATION_SECRET="tobechanged" -e EVENT_SEAL_SECRET="tobechanged" -e VAULT_TYPE="ssv" -e VAULT_MASTER_PASSWORD="tobechanged" -e HOSTS_ALLOWED.0="." -e MONGODB_URI="" -p [port]:9000 \ registry.evertrust.io/horizon:2.6.x

Environment variables

General configuration

Variable Type Description Default

LICENSE

string

A valid Horizon license string, base64-encoded. Can be used if LICENSE_PATH is empty.

LICENSE_PATH

path

Path where an Horizon license file is mounted inside the container. Can be used if the license is not passed directly through LICENSE.

APPLICATION_SECRET

string

Application secret used by Horizon

MONGODB_URI

string

A valid MongoDB URI. See mongo_uri_config.

HOSTS_ALLOWED

array

Array of hosts. Append the array index after a dot (the nth allowed host variable name would be HOSTS_ALLOWED.n).

Your license usually contains newline characters, that you must replace by '\n' when setting it through the environment.

Configure the secrets vault

Variable Type Description Default

VAULT_TYPE

string

Vault backend. ssv for a software encrypted vault. shv for a PKCS#11 HSM.

VAULT_MASTER_PASSWORD

string

When using an ssv vault, this encryption key backs all secrets encrypted in database.

VAULT_MODULE_PATH

string

Used to connect to an HSM.

VAULT_SLOT_ID

string

Used to connect to an HSM.

VAULT_PIN

string

Used to connect to an HSM.

VAULT_LABEL

string

Used to connect to an HSM.

VAULT_ALLOW_MASTER_KEY_GEN

string

Allow key generation on PKCS#11 devices when no existing is found.

Configuring HTTPS

In production, it is strongly recommended to ensure all requests go through a layer of encryption. Configuring TLS for Horizon will allow your reverse proxy to request Horizon data using TLS.

If all settings are left empty, Horizon will generate a self-signed certificate upon startup and still expose its HTTPS endpoint on
Variable Type Description Default

HTTP_PORT

port

Port of the HTTP server

9000

HTTPS_PORT

port

Port of the HTTPS server

9443

HTTPS_KEYSTORE_PATH

string

Location where the keystore containing a server certificate is located.

HTTPS_KEYSTORE_PASSWORD

string

Password for the given keystore, if required by the keystore type

HTTPS_KEYSTORE_TYPE

string

Format in which the keystore is. Can be either pkcs12, jks or pem (a base64-encoded DER certificate)

pkcs12

HTTPS_KEYSTORE_ALGORITHM

string

The key store algorithm

Platform default algorithm

Mailer configuration

Variable Type Description Default

SMTP_HOST

string

SMTP host

SMTP_PORT

string

SMTP port

SMTP_SSL

boolean

Whether SSL should be used

SMTP_TLS

boolean

Whether TLS should be used

SMTP_USER

string

SMTP user

SMTP_PASSWORD

string

SMTP password

Events configuration

Variable Type Description Default

EVENT_CHAINSIGN

boolean

Whether to sign events to verify their integrity

true

EVENT_TTL

duration

Event time to live in database

EVENT_DISCOVERY_TTL

duration

Discovery events time to live. Can be shorter in case a large number of discovery events are logged.

Advanced parameters

Variable Type Description Default

AKKA_ACTOR_SYSTEM

string

Name of the actor system used by Pekko. Useful if you need to run multiple instances of Horizon in the same Kubernetes namespace. Due to compatibility reasons, the variable is still called Akka.

horizon

SESSION_MAXAGE

string

Log in session duration.

15 minutes

HTTP_CERTIFICATE_HEADER

string

Header name in which the client certificate should be sent when using mTLS.

Injecting extra configuration

The Docker image comes with a simple enough configuration to get started and test the software. However, it doesn’t include any way to cluster the software with other instances or to edit other specific configurations. If you need to do so, you can mount custom configuration files, giving you full control over how Horizon behaves.

The mounted folder :

  • MUST contain an pekko.conf file configuring the Pekko cluster. See the reference config to get an idea over what’s configurable.

  • CAN contain a application.conf file containing any extra config options unrelated to clustering.

A typical Docker command would then be :

$ docker run \
   -v [configurationPath]:/opt/horizon/etc/:rw \
   ...
   registry.evertrust.io/horizon:2.6.x

Custom startup scripts

Sometimes, you’ll want to run scripts each time the container starts up in order to configure files in the container or set environment variables. To do so, you’ll need to mount shell scripts into the /docker-entrypoint.d/ directory in the container :

$ docker run \ -v [scriptsPath]:/docker-entrypoint.d/ \
   ...
   registry.evertrust.io/horizon:2.6.x

Where scriptsPath is a directory containing one or multiple shell scripts that will be sourced before running Horizon.