Run Cardano Nodes

📝
Cardano Docker
Search…
📝
Plain Docker
Docker Compose
Kubernetes
Cardano on Kubernetes
Creating a Kubernetes Cluster
Miscellaneous
Known Issues
Run Cardano Nodes
Run a Relay Node
Running a Cardano node is easy. But first, lets check whether your Docker environment is working.
1
$ docker run --rm centos echo "Hello Cardano"
2
Hello Cardano
Copied!
In case you'd like to find out more about what we've just done, take a look at docker run.
In case you don't have Docker installed just yet, take a look at Installing Docker.
Great, this is working. Now lets start the Cardano relay node.
1
$ docker run --detach \
2
    --name=relay \
3
    -p 3001:3001 \
4
    -e CARDANO_UPDATE_TOPOLOGY=true \
5
    -v node-data:/opt/cardano/data \
6
    nessusio/cardano-node run    
Copied!
This will run the Cardano node detached from the current terminal session, publish the default port 3001 on the host network and write the block data to a docker volume. Please make sure that this port is accessible for incoming connections. The above should run on Windows, MacOS, Linux and on x86_64 or arm64 just the same. Full details about this image are given here.
A quick check of our docker stats should show that this container is indeed running.
1
$ docker stats
2
​
3
CONTAINER ID   NAME      CPU %     MEM USAGE / LIMIT    MEM %     NET I/O          BLOCK I/O     PIDS
4
7789064845b5   relay     230.20%   195.7MiB / 7.63GiB   2.50%     15.1MB / 297kB   12.3kB / 0B   15
Copied!
The above shows the output on a RaspberryPi 4, with aggregated CPU usage for the 4 ARM CPUs. The Pi is not very busy at the moment and when fully synced will even be less so.
You can look at the container's console output like this ...
1
$ docker logs -f relay
2
​
3
Running the cardano node ...
4
CARDANO_CONFIG=/opt/cardano/config/mainnet-config.json
5
CARDANO_TOPOLOGY=/opt/cardano/config/mainnet-topology.json
6
CARDANO_BIND_ADDR=0.0.0.0
7
CARDANO_PORT=3001
8
CARDANO_DATABASE_PATH=/opt/cardano/data
9
CARDANO_SOCKET_PATH=/opt/cardano/ipc/socket
10
CARDANO_LOG_DIR=/opt/cardano/logs
11
CARDANO_PUBLIC_IP=
12
CARDANO_CUSTOM_PEERS=
13
CARDANO_UPDATE_TOPOLOGY=true
14
CARDANO_BLOCK_PRODUCER=false
15
cardano-node run --config /opt/cardano/config/mainnet-config.json --topology /opt/cardano/config/mainnet-topology.json --database-path /opt/cardano/data --socket-path /opt/cardano/ipc/socket --host-addr 0.0.0.0 --port 3001
16
Topology update: 17 * * * * root topologyUpdate
17
Initially waiting for 10 minutes ...
18
Listening on http://127.0.0.1:12798
19
[399de2cf:cardano.node.networkMagic:Notice:5] [2021-03-02 19:07:08.28 UTC] NetworkMagic 764824073
20
[399de2cf:cardano.node.basicInfo.protocol:Notice:5] [2021-03-02 19:07:08.28 UTC] Byron; Shelley
21
[399de2cf:cardano.node.basicInfo.version:Notice:5] [2021-03-02 19:07:08.28 UTC] 1.25.1
22
...
Copied!
After a little while, you should be seeing that the node is finding initial peers and starts syncing the block chain.
Stopping the Container
The Cardano node likes to do a graceful shutdown with some database housekeeping before the process terminates. This image has built-in SIGINT (Ctrl+C) redirection so that you can gracefully shut down the node like this ...
1
$ docker stop relay
Copied!
Removing the Container
It is not a good idea to forcefully remove a running container with docker rm -f because this bypasses graceful shutdown and will cause the node to re-validate the entire blockchain. On a fully synchronized node this may take > 15min. Instead, you'd want to stop the container first and then do a regular remove like this ...
1
$ docker rm relay
Copied!
Topology Updater
There is currently no active P2P module in cardano-1.25.x. Your node may call out to well known relay nodes, but you may never have incoming connections. According to this it is necessary to update your topology every hour. At the time of writing, the node doesn't do this on its own.
This functionality has been built into the image as well. The topology updater is triggered by CARDANO_UPDATE_TOPOLOGY=true, which will automatically call a topology update procedure once every hour.
After three hours, the network will have accepted you as a new peer. On consecutive hourly calls it will respond with ...
1.nice to meet you
2.welcome to the topology
3.glad you're staying with us
You can look at the output of the topology updater like this ...
1
$ docker exec -it relay tail /opt/cardano/logs/topologyUpdateResult
2
​
3
{ "resultcode": "201", "datetime":"2021-01-10 18:30:06", "clientIp": "209.250.233.200", "iptype": 4, "msg": "nice to meet you" }
4
{ "resultcode": "203", "datetime":"2021-01-10 19:30:03", "clientIp": "209.250.233.200", "iptype": 4, "msg": "welcome to the topology" }
5
{ "resultcode": "204", "datetime":"2021-01-10 20:30:04", "clientIp": "209.250.233.200", "iptype": 4, "msg": "glad you're staying with us" }
Copied!
Live View Monitoring
After looking at the console output for a while, you may wish to have all the pertinent information available on one screen. Perhaps even without running an additional heavy-weight monitoring process.
An excellent bash based monitor that runs once every few seconds is provided for us by guild-operators. The image incorporates this monitor and configures it automatically according to the node's config
You can start the monitoring process like this ...
1
$ docker exec -it relay gLiveView
Copied!
For details on how to execute a process within a running container, take a look at docker exec.
Command Line Interface
We can also use the image to run Cardano CLI commands.
For this to work, the node must share its IPC socket location, which can then be use in the alias definition.
Define a cardano-cli alias
1
$ alias cardano-cli="docker run -it --rm \
2
  -v node-ipc:/opt/cardano/ipc \
3
  nessusio/cardano-node cardano-cli"
Copied!
Run stateless CLI commands
1
$ cardano-cli query tip --mainnet
2
{
3
    "blockNo": 5418105,
4
    "headerHash": "ae822475da72052b58c7890bc24b191d31d8bd58d9ac7d1e407f7a2e16c3310d",
5
    "slotNo": 23299720
6
}
Copied!
This approach is stateless because all output files that such a CLI process might generate, will be lost when the process terminates, which is when the command returns.
There are two possible solutions to this problem. First, we could exec into to running container and invoke cardano-cli from within the relay process like this ...
1
$ docker exec -it relay bash
2
[email protected]:~# cardano-cli query tip --mainnet
3
{
4
    "blockNo": 5418105,
5
    "headerHash": "ae822475da72052b58c7890bc24b191d31d8bd58d9ac7d1e407f7a2e16c3310d",
6
    "slotNo": 23299720
7
}
8
[email protected]:~# exit
Copied!
All generated output files would live in the relay node and also share its lifecycle i.e. get removed when the container gets removed.
Run stateful CLI commands
A better approach is perhaps to mount some local directory into the container like this ...
1
$ alias cardano-cli="docker run -it --rm \
2
  -v ~/cardano:/var/cardano/local \
3
  -v relay-ipc:/opt/cardano/ipc \
4
  nessusio/cardano-node cardano-cli"
Copied!
and then ...
1
$ cardano-cli query protocol-parameters \
2
    --out-file /var/cardano/local/protocol.json \
3
    --mary-era \
4
    --mainnet
5
​
6
$ cat ~/cardano/protocol.json | grep decent
7
    "decentralisationParam": 0.12
Copied!
Custom Configuration
In this section we define a custom config volume called cardano-relay-config. It holds the mainnet-topology.json that we define according to our needs. Note, that our custom config lives in /var/cardano/config and not in the default location /opt/cardano/config.
Define the Relay Topology
The Relay connects to the World and the Block Producer
1
$ cat << EOF > ~/cardano/config/mainnet-relay-topology.json
2
{
3
  "Producers": [
4
    {
5
      "addr": "relays-new.cardano-mainnet.iohk.io",
6
      "port": 3001,
7
      "valency": 1
8
    },
9
    {
10
      "addr": "bprod.ip.or.dns.name",
11
      "port": 3001,
12
      "valency": 1
13
    }
14
  ]
15
}
16
EOF
Copied!
Setup the config volume
We now copy the topology file that we generated above to the cardano-relay-config volume.
1
$ docker run --name=tmp -v cardano-relay-config:/var/cardano/config centos
2
$ docker cp ~/cardano/config/mainnet-relay-topology.json tmp:/var/cardano/config/mainnet-topology.json
3
$ docker rm -f tmp
Copied!
Start the Relay Node
We can now start the relay again with that custom config volume in place. Of course, we could have mounted the topology file into the container directly, but the volume approach is much to be preferred especially when you consider multiple config/key files in such a volume.
1
$ docker run --detach \
2
    --name=relay \
3
    --restart=always \
4
    -p 3001:3001 \
5
    -e CARDANO_UPDATE_TOPOLOGY=true \
6
    -e CARDANO_PUBLIC_IP="relay01.astorpool.net" \
7
    -e CARDANO_CUSTOM_PEERS="bprod.ip.or.dns.name:3001" \
8
    -e CARDANO_TOPOLOGY="/var/cardano/config/mainnet-topology.json" \
9
    -v cardano-relay-config:/var/cardano/config  \
10
    -v /mnt/disks/data00:/opt/cardano/data \
11
    nessusio/cardano-node run
Copied!
Running a Block Producer
The block producer connects to one or more trusted relays and no other peers.
1
$ cat << EOF > cardano/config/mainnet-bprod-topology.json
2
{
3
  "Producers": [
4
    {
5
      "addr": "relay.ip.or.dns.name",
6
      "port": 3001,
7
      "valency": 1
8
    }
9
  ]
10
}
11
EOF
Copied!
Setup the config volume
Similar to above, we now copy the topology to the cardano-prod-config volume. Additionally, we copy keys and certificates to that volume so that we can then reference it from the container configuration.
1
$ docker run --name=tmp -v cardano-bprod-config:/var/cardano/config centos
2
$ docker cp ~/cardano/config/mainnet-bprod-topology.json tmp:/var/cardano/config/mainnet-topology.json
3
$ docker cp ~/cardano/keys tmp:/var/cardano/config/keys
4
$ docker rm -f tmp
Copied!
Start the Block Producer Node
After having done all the required steps to generate the pool keys, we can now start the block producer like this ...
1
$ docker run --detach \
2
    --name=prod \
3
    --restart=always \
4
    -e CARDANO_BLOCK_PRODUCER=true \
5
    -e CARDANO_TOPOLOGY="/var/cardano/config/mainnet-topology.json" \
6
    -e CARDANO_SHELLEY_KES_KEY="/var/cardano/config/keys/kes.skey" \
7
    -e CARDANO_SHELLEY_VRF_KEY="/var/cardano/config/keys/vrf.skey" \
8
    -e CARDANO_SHELLEY_OPERATIONAL_CERTIFICATE="/var/cardano/config/keys/node.cert" \
9
    -v cardano-prod-config:/var/cardano/config  \
10
    -v /mnt/disks/data01:/opt/cardano/data \
11
    nessusio/cardano-node run
Copied!
The block producer is meant to run on a different host than the relay. We do this for security reasons and also for fail safety. The block producer could connect to more than one redundant relays. If one of them goes down, the block producer would continue to receive transactions and create blocks when scheduled.
Leaderlog Schedule
For a Stake Pool Operator it is important to know when the node is scheduled to produce the next block. We definitely want to be online at that important moment and fulfill our block producing duties. There are better times to do node maintenance.
This important functionality has also been built into nessusio/cardano-tools the image.
First, we also define an alias and ping the node that we want to work with. 
Details about this API are here.
1
$ alias cncli="docker run -it --rm \
2
  -v ~/cardano/keys:/var/cardano/keys \
3
  -v cncli:/var/cardano/cncli \
4
  nessusio/cardano-tools cncli"
5
  
6
NODE_IP=10.128.0.31
7
​
8
cncli ping --host $NODE_IP
9
{
10
  "status": "ok",
11
  "host": "10.128.0.31",
12
  "port": 3001,
13
  "connectDurationMs": 0,
14
  "durationMs": 53
15
}
Copied!
Syncing the database
This command connects to a remote node and synchronizes blocks to a local sqlite database.
1
$ cncli sync --host $NODE_IP \
2
  --db /var/cardano/cncli/cncli.db \
3
  --no-service
4
​
5
...
6
2021-03-04T10:23:19.719Z INFO  cardano_ouroboros_network::protocols::chainsync   > block 5417518 of 5417518, 100.00% synced
7
2021-03-04T10:23:23.459Z INFO  cncli::nodeclient::sync                           > Exiting...
8
​
Copied!
Running leaderlog
We can now obtain the leader schedule for our pool.
1
$ cncli leaderlog \
2
  --pool-id 9e8009b249142d80144dfb681984e08d96d51c2085e8bb6d9d1831d2 \
3
  --shelley-genesis /opt/cardano/config/mainnet-shelley-genesis.json \
4
  --byron-genesis /opt/cardano/config/mainnet-byron-genesis.json \
5
  --pool-vrf-skey /var/cardano/keys/pool/vrf.skey \
6
  --db /var/cardano/cncli/cncli.db \
7
  --tz Europe/Berlin \
8
  --ledger-set current | tee leaderlog.json
9
  
10
cat leaderlog.json | jq -c ".assignedSlots[] | {no: .no, slot: .slotInEpoch, at: .at}"
11
​
12
{"no":1,"slot":165351,"at":"2021-02-26T20:40:42+01:00"}
13
{"no":2,"slot":312656,"at":"2021-02-28T13:35:47+01:00"}
14
{"no":3,"slot":330588,"at":"2021-02-28T18:34:39+01:00"}
15
{"no":4,"slot":401912,"at":"2021-03-01T14:23:23+01:00"}
16
​
Copied!
​