Docker

Overview

Docker builds of cardano-db-sync are available on Docker Hub. ​ Every release is tagged using semantic versioning and pushed to Docker Hub. For instance, images for release 6.0.0 can be pulled from Docker Hub via: ​

$ docker pull inputoutput/cardano-db-sync:6.0.0

​ or the latest development version can be pulled using: ​

$ docker pull inputoutput/cardano-db-sync:master

As the service dependencies are all defined in their own images, the docker-compose.yml is used to provide a self-documenting starting point for your own deployment. It is advised to check a copy into source control and configure it further to meet your requirements. The default configuration uses the IOHK-managed mainnet config, however, you can pass NETWORK=testnet or mount your own config for complete control.

Building the Docker image locally

​ Ensure that you have Nix installed and the IOHK binary cache enabled (instructions). ​ Then run commands within the cardano-db-sync git repository root: ​

docker load -i $(nix-build -A dockerImage --no-out-link)

​ If you have no local changes, the build should be downloaded from the IOHK binary cache

Start in detached mode, then view output from containers​

How To Configure

​ Example configurations are available in the cardano-db-sync repository. You will need: ​

config/
├── configuration.yaml
├── genesis.json
└── pgpass

​

Run the service

​ Assuming you have created the configuration directory as a subdirectory, mount the volume and run [cardano-db-sync]. For example, ​

docker run -v `pwd`/config:/configuration inputoutput/cardano-db-sync:6.0.0

​

Stop the service

CTRL+C

Start the full stack in detached mode, then view output from containers

docker-compose up -d --build && docker-compose logs -f

The initial sync will take some time, but you can stop and resume at any point if retaining the data volumes.

List containers

docker-compose ps -a

Show logs from a specific service

docker-compose logs -f cardano-db-sync

Display running processes

docker-compose top

Stop the stack

docker-compose stop

Rebuild database during a version upgrade

When instructed to rebuild the DB, retaining the cardano-node data volume is important to minimize the sync time:

docker-compose stop
docker volume ls
# copy the volume ending in *_postgres-data to the clipboard
docker volume rm [PASTE]
# copy the volume ending in *_db-sync-data to the clipboard
docker volume rm *_postgres-data [PASTE]
docker-compose pull # this will fetch the update if the `latest` tag is present in your compose file
docker-compose start --force-recreate

Stop and remove containers, networks, images, and volumes

⚠️ Only do this if you need to wipe all state from the host.

docker-compose down -v

Troubleshooting

If you have a port clash on the host, change the mapping in the docker-compose