Running with Docker

🐳 Overview

The easiest way to get started with Ogmios is to use docker. This guide won’t cover installing docker, so make sure you have the Docker daemon installed and running.

Ogmios docker images come in two flavours: cardano-node-ogmios and ogmios. The former is used to run a single container that bundles both a Cardano-node and an Ogmios server running side-by-side. It is likely the easiest way to get started. The latter is a standalone Ogmios server, and you’ll need to run that container in orchestration with a cardano-node; this is made relatively easy with Docker compose.

Images are uploaded to Dockerhub and are tagged using release versions combined with the supported network name, or with :latest if you’re living on the edge. If using the mainnet image you can omit the network name.

imagerepositorytags
cardano-node-ogmioscardanosolutions/cardano-node-ogmioslatest
latest-{NETWORK}
v*.*.*_{CARDANO_NODE_VERSION}
v*.*.*_{CARDANO_NODE_VERSION}-{NETWORK}
ogmioscardanosolutions/ogmioslatest
v*.*.*

Supported NETWORK names:

  • mainnet
  • preview
  • preprod

Building images from sources is currently not available. Building is done outside of Docker to produce a binary static executable which is then mounted as an image. Hence, building the docker image assumes that you’ve built the application to begin with. The Dockerfile expects a pre-built executable in the folder server/bin.

Refer to the next section for building Ogmios. Then simply run docker buildx build --target ogmios to build ogmios' standalone or docker buildx build to build the default cardano-node + ogmios image.

cardano-node-ogmios (easiest)

Running

Assuming you’ve pulled or build the image (otherwise, see below), you can start a cardano-node with an ogmios server in one single command:

$ docker run -it \
  --name cardano-node-ogmios \
  -p 1337:1337 \
  -v cardano-node-ogmios-mainnet-db:/db \
  cardanosolutions/cardano-node-ogmios:latest

Let’s explore a bit the various options:

  • -it is a shorthand for two options -i & -t to enable some interactive support with the container. This is necessary to pass OS signals (e.g. SIGINT from CTRL-C) from the host to the container.

  • --name gives a name to the container, to easily identify it later in commands such as docker container ps.

  • -p instruments docker to bind ports of the container to host. The image exposes 4 ports that can be bound to any (available) port of the host system. Here’s the complete list of TCP ports exposed by the image:

    Port NumberDescription
    1337Ogmios port, for both the WebSocket and the HTTP server.
    3000cardano-node’s relay port
    12788cardano-node’s EKG port
    12798cardano-node’s Prometheus port
  • -v mounts a shared volume with the container on your host machine, either via bind mounts or named volumes.

    Mount PointDescription
    dbPersist the cardano-node’s database to avoid re-syncing the chain whenever a new container is run. This is done on every version upgrade and is recommended for most use-cases. Make sure to use different names for different networks as the data aren’t compatible between them!
    ipcBind /ipc to get access to the cardano-node’s local socket if you use the image in a multi-container stack with an external Haskell client.

Find more about run options in the docker user documentation.

Ogmios standalone (more advanced)

Running (bare hands)

Assuming that you have a cardano-node running, with its domain socket (node.socket) available under ./ipc, you may start a standalone Ogmios container as follows:

$ docker run --rm \
  --name ogmios \
  -p 1337:1337 \
  -v ./ipc:/ipc \
  cardanosolutions/ogmios:latest \
    --node-socket /ipc/node.socket \
    --node-config /config/mainnet/cardano-node/config.json \
    --host 0.0.0.0

Note that the --host argument is necessary to bind the server from within the container.

Configuration

Configuration files are available from within the image under /config in folders named after the supported networks.

/config
 β”œβ”€β”€ mainnet
 β”‚Β Β  β”œβ”€β”€ cardano-node
 β”‚Β Β  β”‚Β Β  β”œβ”€β”€ config.json
 β”‚Β Β  β”‚Β Β  └── topology.json
 β”‚Β Β  └── genesis
 β”‚Β Β      β”œβ”€β”€ alonzo.json
 β”‚Β Β      β”œβ”€β”€ byron.json
 β”‚Β Β      β”œβ”€β”€ conway.json
 β”‚Β Β      └── shelley.json
 β”œβ”€β”€ preprod
 β”‚Β Β  β”œβ”€β”€ cardano-node
 β”‚Β Β  β”‚Β Β  β”œβ”€β”€ config.json
 β”‚Β Β  β”‚Β Β  └── topology.json
 β”‚Β Β  └── genesis
 β”‚Β Β      β”œβ”€β”€ alonzo.json
 β”‚Β Β      β”œβ”€β”€ byron.json
 β”‚Β Β      β”œβ”€β”€ conway.json
 β”‚Β Β      └── shelley.json
 └── preview
     β”œβ”€β”€ cardano-node
     β”‚Β Β  β”œβ”€β”€ config.json
     β”‚Β Β  └── topology.json
     └── genesis
         β”œβ”€β”€ alonzo.json
         β”œβ”€β”€ byron.json
         └── shelley.json

Running (docker-compose)

Alternatively, you may use Docker’s compose to run either Ogmios standalone, or an orchestration of cardano-node and Ogmios talking to each other. Compose is a handy tool to orchestrate multiple services packaged as containers. It works from a compose file which is available in the project repository, get it via:

$ git clone --depth 1 --recursive --shallow-submodules git@github.com:cardanosolutions/ogmios.git
$ cd ogmios

Then, starts the components stack using:

$ docker-compose up

πŸ‘†This will run and connect:

Once finish, tear the stack down using:

$ docker-compose down

Configuration

The compose file allows for minimal (albeit useful) configuration parameters via environment variables:

VariableDescriptionValuesDefault
NETWORKWhich Cardano network to connect to. This impacts both Ogmios and the underlying Cardano node.mainnet, preview, preprodmainnet
OGMIOS_PORTWhich ports to listen to (both for WebSockets and health endpoints)Any valid port number.1337

Ogmios doesn’t use any form of persistent storage, but cardano-node does. The mainnet, preview and preprod databases are not compatible, so it is recommended to instrument docker-compose to use different namespaces for different networks (so that you can switch from one another without risking any database conflicts). Compose can do this easily by passing an extra flag: --project-name.

For example, for running cardano-node + ogmios on the preprod network, listening to tcp/1338, do:

$ NETWORK=preprod OGMIOS_PORT=1338 docker-compose --project-name cardano-ogmios-preprod up