Cardano Node Docker Image for ARM64 devices 🐳
In this project you will find the files to build a docker image on Linux containing all the needed files to run a Cardano full node. The docker image can run on any arm64 device (such as a RaspberryPi, Mac Mini M1, etc.). The node can be configured as a relay or block production node.
Why using docker image to run a Cardano node?
The elegant thing about a Cardano node deployed as a Docker image is that it can be installed seamlessly and launched out of the box. If you ever decide to remove it, you only have to delete one file - the image. Another advantage is that the created image can run on any operating system where Docker is installed. Using Docker reduces the complexity and effort of setting up a Cardano node compared to the traditional way (for example, you don't have to deal with systemd settings).
System requirements
- CPU: ARM64 processor min 2 cores at 2GHz or faster.
- Memory: 12GB of RAM.
- Storage: 50 GB.
- OS: Linux (recommended Ubuntu)
- Additional Software: Docker
- Broadband: 10 Mbps +
tip
If you intend to use a Raspberry Pi 8GB RAM for the deployment of this docker image, please follow our Server Setup guide first. This guide describes how to optimize the Hardware to satisfy the above listed system requirements.
1.Install Docker
The installation of Docker varies from operating system to operating system. For this reason, we share some helpful and good installation guide links for the different operating systems.
2. Set-up the Environment & Download Files
Create the repositories on your host system first. They will hold the files to build the docker image as well as the Cardano node configuration files.
cd ${HOME}
sudo mkdir Cardano-node-docker
cd Cardano-node-docker
sudo mkdir -p node/db && sudo mkdir -p node/files && sudo mkdir -p dockerfiles/files
The files to build the docker images will be downloaded from MINI1 pool GitHub
cd dockerfiles
sudo wget -N https://raw.githubusercontent.com/jterrier84/Cardano-node-docker/master/dockerfiles/armada-cn-arm64.dockerfile
sudo wget -N https://raw.githubusercontent.com/jterrier84/Cardano-node-docker/master/dockerfiles/build.sh
sudo chmod +x build.sh
cd files
sudo wget -N https://raw.githubusercontent.com/jterrier84/Cardano-node-docker/master/dockerfiles/files/run.sh
sudo wget -N https://raw.githubusercontent.com/jterrier84/Cardano-node-docker/master/dockerfiles/files/tx-submit-service
sudo chmod +x run.sh
sudo chmod +x tx-submit-service
cd ${HOME}/Cardano-node-docker/node
sudo wget -N https://raw.githubusercontent.com/jterrier84/Cardano-node-docker/master/node/run-node.sh
sudo chmod +x run-node.sh
Download the latest official Cardano node configuration files from the IOHK repository and store them on our host system.
tip
For the sake of this tutorial we will download and set up the configuration files for the Cardano testnet. If you need the files for the mainnet just replace "testnet" with "mainnet" here below.
tip
As the configuration files might require modifications over time, it is way more practical to have them stored on the host, rather than have them stored inside the Docker container. Our Cardano Docker node will have access to these files from the container.
cd ${HOME}/Cardano-node-docker/node/files
export NODE_CONFIG="testnet"
export NODE_BUILD_NUM=$(curl https://hydra.iohk.io/job/Cardano/iohk-nix/cardano-deployment/latest-finished/download/1/index.html | grep -e "build" | sed 's/.*build\/\([0-9]*\)\/download.*/\1/g')
sudo wget -N https://hydra.iohk.io/build/${NODE_BUILD_NUM}/download/1/${NODE_CONFIG}-config.json
sudo wget -N https://hydra.iohk.io/build/${NODE_BUILD_NUM}/download/1/${NODE_CONFIG}-byron-genesis.json
sudo wget -N https://hydra.iohk.io/build/${NODE_BUILD_NUM}/download/1/${NODE_CONFIG}-shelley-genesis.json
sudo wget -N https://hydra.iohk.io/build/${NODE_BUILD_NUM}/download/1/${NODE_CONFIG}-alonzo-genesis.json
sudo wget -N https://hydra.iohk.io/build/${NODE_BUILD_NUM}/download/1/${NODE_CONFIG}-topology.json
sudo wget -O tx-submit-mainnet-config.yaml https://raw.githubusercontent.com/input-output-hk/cardano-node/master/cardano-submit-api/config/tx-submit-mainnet-config.yaml
tip
The directory /files contains the downloaded Cardano node configuration files.
The /db directory will host the Cardano blockchain once the Docker node is started. It is important that the blockchain data are stored on the host system and not inside the Docker container, otherwise the entire blockchain would be deleted every time the Docker container is removed.
3. Build the Cardano node docker image
At this point it's time to build the docker image. The image will include:
- cardano-node & cardano-cli v1.34.1 - Cardano binaries to run the node (Download compiled binaries from Armada Alliance GitHub)
- gLiveView - Monitoring tool for the Cardano node
- ScheduledBlocks - Tool to query the scheduled slots for a block production node. (Credits for this tool goes to SNAKE POOL)
- Cardano Submit Transaction API - API to connect with a Cardano wallet (e.g. Nami) to send transactions via your own full node
cd ${HOME}/Cardano-node-docker/dockerfiles
sudo ./build.sh
The process might take some minutes.
Once the process is done, you can use the command to see the list of all Docker images on your host system:
docker images
You should see your Cardano node docker image in the list, e.g.
REPOSITORY TAG IMAGE ID CREATED SIZE
armada/armada-cn 1.34.1 da4414775ce6 37 seconds ago 619MB
<none> <none> f3891eef21e4 3 minutes ago 1.09GB
All we need is the "armada/armada-cn" image. You can delete the others in the list to free up space on your harddrive, e.g.
docker rmi f3891eef21e4
4. Start node
Let's first configure the run-node.sh script to match your host system environment.
cd ${HOME}/Cardano-node-docker/node
sudo nano run-node.sh
Edit the configuration section according to your setup.
tip
If you are running the node as relay node, you can ignore the paramter CN_KEY_PATH.
caution
Important: Change the directory paths CN_CONFIG_PATH and CN_DB_PATH to the corresponding locations on your host.
##Configuration for relay and block producing node
CNIMAGENAME="armada/armada-cn" ## Name of the Cardano docker image
CNVERSION="1.34.1" ## Version of the cardano-node. It must match with the version of the docker i>
CNNETWORK="testnet" ## Use "mainnet" if connecting node to the mainnet
CNMODE="relay" ## Use "bp" if you configure the node as block production node
CNPORT="3001" ## Define the port of the node
CNPROMETHEUS_PORT="12799" ## Define the port for the Prometheus metrics
CN_CONFIG_PATH="/home/julienterrier/Cardano-node-docker/node/files" ## Path to the folder where the Cardano config files are stored on the host>
CN_DB_PATH="/home/julienterrier/Cardano-node-docker/node/db" ## Path to the folder where the Cardano database (blockchain) will be stored o>
CN_RTS_OPTS="+RTS -N2 -I0.1 -Iw3600 -A64m -AL128M -n4m -F1.1 -H3500M -O3500M -RTS" ## RTS optimization parameters
CN_BF_ID="" ## Your blockfrost.io project ID (for ScheduledBlock script)
CN_POOL_ID="" ## Your stake pool ID (for ScheduledBlock script)
CN_POOL_TICKER="" ## Your pool ticker (for ScheduledBlock script)
CN_VRF_SKEY_PATH="" ## Name of the vrf.skey file. It must be located in the same directory as CN_KEY_PATH (for ScheduledBlock script)
CN_KEY_PATH="" ## Path to the folder where the OP certificate and keys are stored on the host system (for block production node only)
After making the changes, save and close the file.
Ctrl+o & ENTER & Ctrl+x
You can now run the docker image.
sudo ./run-node.sh
Check the running status of the docker container
You can check the running status of the docker container at any time with:
docker ps -a
If the docker node started successfully, you might see something like this:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
fed0cfbf7d86 armada/armada-cn:1.34.1 "bash title=">_ Terminal" -c /home/carda…" 12 seconds ago Up 10 seconds (healthy) 0.0.0.0:3001->3001/tcp, :::3001->3001/tcp, 0.0.0.0:12799->12798/tcp, :::12799->12798/tcp cardano-node-testnet-1.34.1
You can also check the logs of the running cardano-node:
docker logs -f {CONTAINER ID}
To exit the logs press Ctrl+c
Stop/Restart/Delete the Docker Cardano node
To stop the running Cardano node execute:
docker stop {CONTAINER ID}
A stopped container can be started again with:
docker start {CONTAINER ID}
A stopped container can also be deleted. Once deleted, it can not be started with the command above again.
docker rm {CONTAINER ID}
If you like to start the node again, after having removed the docker container, just run the run-node.sh script.
sudo ${HOME}/Cardano-node-docker/node/run-node.sh
Monitor the Docker Cardano node with gLiveView
While the docker Cardano node is running, you can monitor its status with the tool gLiveView.
docker exec -it {CONTAINER ID} /home/cardano/pi-pool/scripts/gLiveView.sh
Check the scheduled slots of the block production node
Our Docker image contains the ScheduledBlocks python script from SNAKE pool. This tool allows to query the blockchain for the scheduled slots for your block production node.
Before using the script, make sure that the right configurations are set in our shell script run-node.sh. Set the following variables:
CN_BF_ID="mainnetd9PBzlK7KB7wWko8NTKUwJIsHfvEKNaV" ## Your blockfrost.io project ID (for ScheduledBlock script)
CN_POOL_ID="c3e7025ebae638e994c149e5703e82619b31897c9e1d64fc684f81c2" ## Your stake pool ID (for ScheduledBlock script)
CN_POOL_TICKER="MINI1" ## Your pool ticker (for ScheduledBlock script)
CN_VRF_SKEY_PATH="scheduledblocks.vrf.skey" ## Name of the vrf.skey file. It must be located in the same directory as CN_KEY_PATH (for ScheduledBlock script)
CN_KEY_PATH="/home/julienterrier/Cardano-node-docker/node/files/.keys" ## Path to the folder where the OP certificate and keys are stored on the host system
Start the ScheduledBlocks.py script and follow the instructions on the terminal:
docker exec -it {CONTAINER ID} python3 /home/cardano/pi-pool/scripts/ScheduledBlocks/ScheduledBlocks.py
Run node in P2P (peer-to-peer) mode
caution
Run node in P2P (peer-to-peer) mode
Although P2P can be enabled on Node version 1.34.1, IOHK does not yet recommend using it because it has not yet been officially released.
:::
In order for a node to connect to other peers in the network, a mechanism must be set in place. On Cardano the actual official mechanism forsees the use of a static network topology file, where the IP adress and port number of known peers can be configured. To automate this process, a tool called TopologyUpdater exists. IOHK is working on a more decentralized mechanism, called peer-to-peer networking. The P2P networking doesn't require the configuration of a static network topology file anymore.
To configure P2P on a relay node, we need to make some changes in the -topology.json and -config.json files:
cd ${HOME}/Cardano-node-docker/node/files
sed -i 's+"TurnOnLogging": true,+"TurnOnLogging": true,\n "TestEnableDevelopmentNetworkProtocols": true,\n "EnableP2P": true,\n "MaxConcurrencyBulkSync": 2,\n "MaxConcurrencyDeadline": 4,\n "TargetNumberOfRootPeers": 50,\n "TargetNumberOfKnownPeers": 50,\n "TargetNumberOfEstablishedPeers": 25,\n "TargetNumberOfActivePeers": 10,+' *-config.json
Open the *-topology.json file with the nano editor and replace the entire content with:
sudo nano testnet-topology.json ##use mainnet-topology.json for mainnet
Don't forget to enter the IP and Port of your block production node in the respective lines below:
{
"LocalRoots": {
"groups": [
{
"localRoots": {
"accessPoints": [
{
"address": "[IP block Production node]",
"port": [Port block production node]
}
],
"advertise": false
},
"valency": 1
}
]
},
"PublicRoots": [
{
"publicRoots" : {
"accessPoints": [
{
"address": "relays-new.cardano-mainnet.iohk.io",
"port": 3001
}
],
"advertise": true
},
"valency": 1
}
],
"useLedgerAfterSlot": 0
}
To configure P2P on the block production node, the steps are the same as above, only the content of the *-topology.json is different:
{
"LocalRoots": {
"groups": [
{
"localRoots": {
"accessPoints": [
{
"address": "[IP Relay 1]",
"port": [Port Relay 1]
},
{
"address": "[IP Relay 2]",
"port": [Port Relay 2]
}
],
"advertise": false
},
"valency": 2
}
]
},
"PublicRoots": []
}
Your nodes are now ready to run in P2P mode.