Several modules in this course require a local source of Cardano chain data. This lesson gets that infrastructure running and explains the tooling landscape around it — including what's coming next.
Before You Set Up: Understanding Cardano Up
Before diving into the setup steps, it's worth knowing about Cardano Up — a CLI tool built by Blink Labs that manages Cardano infrastructure.
What is Cardano Up?
Cardano Up is a package manager for Cardano services written in Go by Blink Labs. If you completed lesson 099.3 you'll recognise its CLI — it's built with Cobra, the same library you used to build your own multi-command CLI tool.
It handles the things that make local node setup painful:
- Pulling the right Docker images
- Exposing the Unix socket outside the container (so your Go tools can connect to it)
- Setting environment variables like
CARDANO_NODE_SOCKET_PATHautomatically - Managing network-specific configuration
- Running multiple network contexts (preprod and mainnet) side by side without conflicts
Instead of writing Docker compose files and managing volumes manually, you get:
cardano-up install cardano-node
eval $(cardano-up context env)It currently manages: cardano-node, Dolos, Dingo, Ogmios, Kupo, Mithril, and others.
Why aren't we using Cardano Up to run Dolos?
This is a fair question — Cardano Up can install Dolos, so why do it manually?
Two reasons:
**1. The manual setup teaches concepts you need throughout the course.**The setup below makes you choose your socket path, network magic, and which APIs to enable. Those aren't arbitrary config details — you'll use them directly when connecting Adder in Module 201 and querying chain data in Module 202. If Cardano Up handled all of that silently, you'd hit those modules not knowing where your socket is or why magic: 1 matters.
**2. Dolos is the right tool for learning, regardless of what comes next.**Dolos is a lightweight data node — it doesn't validate blocks or participate in consensus. Running it requires around 5–10 GB of disk space for preprod chain data. A full node like Dingo is a different proposition in terms of disk: Preview testnet alone requires ~50 GB, Preprod ~150 GB, Mainnet ~400 GB. For learners who just want to write Go code against a local node, Dolos keeps that barrier low.
Cardano Up makes sense as a production ops tool once you understand what it's managing. This lesson gives you that understanding first.
What's coming: Dingo
Dingo is Blink Labs' full Cardano node implementation in Go. It is currently minting blocks on the Preview testnet and is under active development. It is not yet recommended for mainnet use.
When Dingo reaches production readiness, the setup story for this course changes:
cardano-up install dingo
eval $(cardano-up context env)That single command gives you a Go-native Cardano node built by the same team behind Bursa, Apollo, Adder, and gOuroboros — the full course stack becomes Blink Labs end to end. Bear in mind that running a full node requires significantly more disk space than Dolos. For learners, Dolos remains the accessible on-ramp.
For now, Dolos is the stable, lightweight choice. The setup below will serve you through the course. When Dingo stabilises, this lesson will be updated.
Setting Up Dolos
What Is Dolos?
Dolos is a Cardano data node built by TxPipe, written in Rust. It is not a full Cardano node — it does not validate blocks, produce blocks, or participate in consensus. It does one thing: keep a local, up-to-date copy of the chain and serve that data to clients through several APIs.
From the official docs:
"keeping an updated copy of the ledger and replying to queries from trusted clients, while requiring a small fraction of the resources."
What Problem Does Dolos Solve?
When tools like Adder follow the chain, they need somewhere to connect. There are two options:
Option
How it works
Trade-offs
Public relay (TCP)
Connect directly to a public Cardano relay over the internet
Simple, no local setup, but depends on a third party's uptime
Dolos (local socket)
Run Dolos locally; tools connect via a Unix socket
Fast, local, stable — you control your own data source
For this course, tools like Adder connect to Dolos via a local Unix socket. This mirrors how real indexers are deployed — co-located with a data node rather than depending on public infrastructure.
Dolos also exposes multiple APIs beyond the Ouroboros socket — including gRPC and a Mini Blockfrost HTTP endpoint — making it useful across modules as we move into querying and application development.
How Dolos Fits in the Stack
Cardano Network (preprod relays)
↓ N2N over TCP (Ouroboros)
[ Dolos ] ← syncing the chain continuously
↓ via Unix socket / gRPC / HTTP
[ Your tools ] ← Adder, Apollo, your applicationDolos connects outward to the Cardano network and maintains a local copy of the chain. Your tools connect inward to Dolos. Your application code never needs to reach out to the wider network directly.
Prerequisites
- Linux, macOS, or Windows
- ~5–10 GB free disk space for preprod chain data (1 week of history)
Step-by-Step Instructions
Step 1: Install Dolos
The TxPipe docs (docs.txpipe.io/dolos) cover all installation options:
The binary install methods below download the Dolos executable directly to your machine. This is why the prerequisites list disk space — Dolos stores the chain data it syncs locally on your hard drive. If you prefer not to install a binary, Docker is also supported (see below).
macOS / Linux (shell script):
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/txpipe/dolos/releases/latest/download/dolos-installer.sh | shmacOS / Linux (Homebrew):
brew install txpipe/tap/dolosDocker (alternative):
docker run -d \
-v $(pwd)/dolos.toml:/etc/dolos/dolos.toml \
-v $(pwd)/data:/data \
ghcr.io/txpipe/dolos:latest daemonDocker avoids installing a binary locally but you still need the same disk space for the chain data volume. For this course we recommend the binary install — it makes running dolos daemon from your terminal simpler.
Verify the binary install:
dolos --versionStep 2: Configure with dolos init
Create a directory for your Dolos data and config, then run the interactive setup:
mkdir ~/dolos
cd ~/dolos
dolos initdolos init asks a series of questions and generates a dolos.toml configuration file. Here is the full set of choices for this course and the reasoning for each:
Note: On a fresh install with no existing data,
dolos initwill also ask whether you want to use Mithril for bootstrapping. Answer Yes — Mithril uses cryptographic snapshots to sync the chain quickly without downloading everything from genesis. This question is skipped if Dolos detects existing chain data on disk.
Question
Answer
Why
Which network are you connecting to?
Cardano PreProd
The testnet we use throughout the course
Do you want us to provide the genesis files?
Yes
Dolos downloads the genesis files automatically — only say No if you're supplying them yourself for a custom network
Which remote peer (relay) do you want to use?
preprod-node.world.dev.cardano.org:30000 (default)
The official IOG/Intersect preprod relay — accept the default
How much history do you want to keep on disk?
1 week
Enough for development without excessive disk usage. "Keep everything" is unnecessary for this course.
Do you want to use Mithril for bootstrapping? (fresh install only)
Yes
Syncs chain history from a verified snapshot rather than from genesis — much faster
Serve clients via gRPC?
Yes
The gRPC API is used in later modules for querying chain state
Serve clients via Blockfrost-like HTTP endpoint?
Yes
Useful for Module 202 queries — enable it now rather than reconfigure later
Serve clients via TRP endpoint?
No
Transaction submission is handled by Apollo/gOuroboros in this course, not Dolos
Serve clients via Ouroboros (node socket)?
Yes
This is what Adder connects to in Module 201 — the most critical option
Act as a relay for other nodes?
No
We're running Dolos as a local dev tool, not a network participant
Expected result:
config saved to dolos.toml
Dolos is ready!
- run `dolos daemon` to start the nodeStep 3: Bootstrap the Chain
If this is a fresh Dolos installation (no existing data), you need to sync chain history before running the daemon. Rather than syncing from genesis, Dolos can import a Mithril snapshot — a cryptographically verified point-in-time copy of the chain state:
dolos bootstrap mithrilThis downloads and imports the snapshot. It may take several minutes depending on your connection speed.
**Why it matters:**Syncing preprod from genesis would take a very long time. Mithril bootstrapping gets you to a recent chain tip quickly without sacrificing data integrity.
If you already have existing Dolos data from a previous setup,
dolos initwill detect it and skip the bootstrap automatically.
Step 4: Run the Daemon
From your ~/dolos directory:
dolos daemonDolos connects to the upstream relay and begins following the live chain. You will see log output as it syncs forward to the current tip. Once there, slot numbers in the logs slow to roughly one every 20 seconds — the preprod block time.
The dolos.socket file is created in your ~/dolos directory while the daemon is running. It disappears when Dolos stops. Keep this terminal open while working through the course modules.
Values to Note
When configuring tools in subsequent modules, you will need:
Value
Where to find it
Example
Socket path
The full path to dolos.socket in the directory where you ran dolos daemon
/home/yourname/dolos/dolos.socket
Network magic
dolos.toml → [upstream] → network_magic
1
Common Issues
dolos.socket: no such file or directory
Dolos is not running, or you are looking in the wrong directory. Start dolos daemon from your ~/dolos directory and confirm the socket file appears there.
Bootstrap fails or is very slow
Check your internet connection. If Mithril bootstrapping fails, try dolos bootstrap relay as a fallback — it syncs directly from a relay node (slower but more resilient).
Dolos stops unexpectedly
Check the terminal output for errors. A common cause is insufficient disk space — the chain data grows over time. Ensure you have headroom beyond the initial snapshot size.
Summary
Made by
TxPipe
Language
Rust
Role in this course
Local source of Cardano chain data for Adder and other tools
APIs exposed
Unix socket (Ouroboros), gRPC, Mini Blockfrost HTTP
Config file
dolos.toml in your Dolos directory
Network
Preprod — magic 1
Key commands
dolos init → dolos bootstrap mithril → dolos daemon