2 Lovelaces

Introduction

Cardano node is the core of the Cardano blockchain. It's responsible for handling networking, consensus (Ouroboros), and ledger validation. Setting it up traditionally involves manual dependency management and complex configuration. Docker changes this by packaging everything into a portable container.

Containerizing Cardano node transforms setup into a simple docker-compose up command.

Why Docker?

Simplified Setup – Works identically on Linux, macOS, Windows

Isolation – Separate from other system applications

Multi-Network – Run Preprod, Mainnet, Preview simultaneously

Easy Updates – Pull new images, rollback instantly

Integration-Ready – Add wallet, monitoring tools easily

Prerequisites

Ensure you have:

Docker Engine (20.10+) & Docker Compose (2.0+)

Install from docker.com

System Requirements

Network	RAM	Disk Space
Preview/Preprod	4-8 GB	50 GB
Mainnet	16 GB	150+ GB (SSD)

Also need: Stable internet, basic command-line knowledge, familiarity with Docker concepts.

Understanding Cardano Networks

The Three Networks

Mainnet – Production blockchain with real ADA

Storage: ~150+ GB | Sync: 3-6 hours (with Mithril)

Use for: Production dApps, live stake pools

Preprod – Stable test network (mirrors Mainnet)

Storage: ~20-40 GB | Sync: 1-2 hours (with Mithril)

Use for: Pre-production testing, integration testing

Preview – Experimental (latest features first)

Storage: ~10-20 GB | Sync: 30-60 minutes (with Mithril)

Use for: Testing new features, rapid prototyping

Quick Decision

Goal	Network
Learning	Preview/Preprod
Testing dApp	Preview → Preprod → Mainnet
Production	Mainnet

Network ports: Preprod (3001), Mainnet (3002), Preview (3003)

This guide uses Preprod for the best balance of stability and speed.

Basic Setup – Your First Node

Using Pre-Built Images

We'll use ghcr.io/blinklabs-io/cardano-node:latest (maintained by Blink Labs) for instant setup. Building from source takes 30-60 minutes and is only needed for custom modifications.

Create Your Setup

mkdir cardano-node-docker && cd cardano-node-docker
nano docker-compose.yml

Minimal Preprod Configuration

services:
	cardano-node-preprod:
    image: ghcr.io/blinklabs-io/cardano-node:latest
    container_name: cardano-node-preprod
    restart: unless-stopped
    environment:
      - NETWORK=preprod
    ports:
      - "3001:3001"    # P2P port
    volumes:
      - cardano-preprod-data:/data/db
      - cardano-preprod-ipc:/ipc
      - cardano-preprod-config:/opt/cardano/config
    networks:
      - cardano-network

volumes:
  cardano-preprod-data:
  cardano-preprod-ipc:
  cardano-preprod-config:

networks:
  cardano-network:
    driver: bridge

Start it:

docker compose up -d

Your first Cardano node is running!

Advanced Configuration (with health checks & metrics)

services:
  cardano-node-preprod:
    image: ghcr.io/blinklabs-io/cardano-node:latest
    container_name: cardano-node-preprod
    restart: unless-stopped
    environment:
      - NETWORK=preprod
      # - DEBUG=1  # Uncomment for detailed logs
      # - RESTORE_NETWORK=false  # Disable Mithril fast sync
    ports:
      - "3001:3001"    # P2P port
      - "12798:12798"  # Prometheus metrics
    volumes:
      - cardano-preprod-data:/data/db
      - cardano-preprod-ipc:/ipc
      - cardano-preprod-config:/opt/cardano/config
    networks:
      - cardano-network
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:12798/metrics"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

volumes:
  cardano-preprod-data:
  cardano-preprod-ipc:
  cardano-preprod-config:

networks:
  cardano-network:
    driver: bridge

Multi-Network (Preprod, Mainnet, Preview)

services:
  # Preprod - Default (starts without profile)
  cardano-node-preprod:
    image: ghcr.io/blinklabs-io/cardano-node:latest
    container_name: cardano-node-preprod
    restart: unless-stopped
    environment:
      - NETWORK=preprod
    ports:
      - "3001:3001"
    volumes:
      - cardano-preprod-data:/data/db
      - cardano-preprod-ipc:/ipc
      - cardano-preprod-config:/opt/cardano/config
    networks:
      - cardano-network

  # Mainnet - Use profile
  cardano-node-mainnet:
    image: ghcr.io/blinklabs-io/cardano-node:latest
    container_name: cardano-node-mainnet
    restart: unless-stopped
    environment:
      - NETWORK=mainnet
    ports:
      - "3002:3001"    # Different port to avoid conflicts
    volumes:
      - cardano-mainnet-data:/data/db
      - cardano-mainnet-ipc:/ipc
    networks:
      - cardano-network
    profiles:
      - mainnet

  # Preview - Use profile
  cardano-node-preview:
    image: ghcr.io/blinklabs-io/cardano-node:latest
    container_name: cardano-node-preview
    restart: unless-stopped
    environment:
      - NETWORK=preview
    ports:
      - "3003:3001"
    volumes:
      - cardano-preview-data:/data/db
      - cardano-preview-ipc:/ipc
    networks:
      - cardano-network
    profiles:
      - preview

volumes:
  cardano-preprod-data:
  cardano-preprod-ipc:
  cardano-preprod-config:
  cardano-mainnet-data:
  cardano-mainnet-ipc:
  cardano-preview-data:
  cardano-preview-ipc:

networks:
  cardano-network:
    driver: bridge

Usage:

docker compose up -d                              # Preprod only
docker compose --profile mainnet up -d            # + Mainnet
docker compose --profile mainnet --profile preview up -d  # All three

Volumes & Data Persistence

volumes:
  - cardano-preprod-data:/data/db      # Blockchain (~20-40 GB)
  - cardano-preprod-ipc:/ipc           # Socket for CLI/Wallet
  - cardano-preprod-config:/opt/cardano/config  # Configs

Data survives restarts

Shared between services

docker compose down -v deletes data

Makefile for Easy Management

.PHONY: help start stop restart logs status sync clean

# Default target
help:
	@echo "Cardano Node Management Commands:"
	@echo "  make start       - Start Preprod node"
	@echo "  make stop        - Stop all nodes"
	@echo "  make restart     - Restart Preprod node"
	@echo "  make logs        - View Preprod logs"
	@echo "  make status      - Check node status"
	@echo "  make sync        - Check sync progress"
	@echo "  make clean       - Remove containers (keeps data)"
	@echo "  make clean-all   - Remove everything including data"
	@echo ""
	@echo "Network-specific:"
	@echo "  make start-mainnet   - Start Mainnet node"
	@echo "  make start-preview   - Start Preview node"

# Basic operations
start:
	docker compose up -d cardano-node-preprod

stop:
	docker compose stop

restart:
	docker compose restart cardano-node-preprod

logs:
	docker compose logs -f cardano-node-preprod

status:
	docker ps --filter "name=cardano-node"

# Check sync progress
sync:
	docker exec cardano-node-preprod cardano-cli query tip --testnet-magic 1

# Network-specific commands
start-mainnet:
	docker compose --profile mainnet up -d

start-preview:
	docker compose --profile preview up -d

# Cleanup
clean:
	docker compose down

clean-all:
	@echo "This will delete all blockchain data!"
	@read -p "Are you sure? [y/N] " -n 1 -r; \
	echo; \
	if [[ $$REPLY =~ ^[Yy]$$ ]]; then \
		docker compose down -v; \
	fi

# Update images
update:
	docker compose pull
	docker compose up -d

Usage: make start, make logs, make sync, make stop

Quick Start Steps

Create files: docker-compose.yml and Makefile (optional)

Start: make start or docker compose up -d

Watch logs: make logs or docker compose logs -f cardano-node-preprod

Check sync: make sync or docker exec cardano-node-preprod cardano-cli query tip --testnet-magic 1

Look for "syncProgress": "100.00" when synced!

Port Mappings

ports:
- "3001:3001" # P2P (required)
- "12798:12798" # Metrics (optional)

Network	Host Port
Preprod	3001
Mainnet	3002
Preview	3003

Common Commands

docker compose up -d              # Start
docker compose stop               # Stop
docker compose logs -f            # View logs
docker compose restart            # Restart
docker compose down               # Remove (keeps data)
docker compose down -v            # Remove all (deletes data)
docker compose pull && docker compose up -d  # Update

First Start Process

Downloads image (~2-3 GB, once)

Creates volumes

Downloads Mithril snapshot

Restores blockchain

Syncs remaining blocks

Ready!

Time: 1-2 hours for Preprod

Tip: Mithril reduces sync from days to hours. Disable with RESTORE_NETWORK=false.

Verify It's Working

docker ps # Check status
make sync # Check sync progress

Success! Your Cardano node is running.

CLI & Wallet Integration

Run CLI commands directly:

docker exec cardano-node-preprod cardano-cli query tip --testnet-magic 1

Add Wallet service to docker-compose.yml:

cardano-wallet:
  image: cardanofoundation/cardano-wallet:latest
  ports:
    - "8090:8090"
  volumes:
    - cardano-preprod-ipc:/ipc
  profiles:
    - wallet

Start:

docker compose --profile wallet up -d

API: curl http://localhost:8090/v2/network/information

Conclusion

You've successfully containerized a Cardano node

Resources: docs.cardano.org | github.com/blinklabs-io

Happy building on Cardano!