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:
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,
:latest if you’re living on the edge. If using the
you can omit the network name.
Supported NETWORK names:
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
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.
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
-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:
|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.
|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!|
Find more about run options in the docker user documentation.
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/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 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
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 firstname.lastname@example.org:cardanosolutions/ogmios.git $ cd cardano-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
The compose file allows for minimal (albeit useful) configuration parameters via environment variables:
|Which Cardano network to connect to. This impacts both Ogmios and the underlying Cardano node.|
|Which ports to listen to (both for WebSockets and health endpoints)||Any valid port number.|
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:
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