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.

Supported NETWORK names:

• mainnet
• preview
• preprod

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 Number	Description
  1337	Ogmios port, for both the WebSocket and the HTTP server.
  3000	cardano-node’s relay port
  12788	cardano-node’s EKG port
  12798	cardano-node’s Prometheus port

• -v mounts a shared volume with the container on your host machine, either via bind mounts or named volumes.

  Mount Point	Description
  db	Persist 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!
  ipc	Bind /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:

• A Cardano node, connected to mainnet.
• An Ogmios server using the latest Dockerhub build, listening to localhost on port: 1337.

Once finish, tear the stack down using:

$ docker-compose down

Configuration

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

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