Cardano Node at Home: Getting Started
Build a Cardano Node using Docker & Ubuntu Server 22.04.2 LTS
Welcome to the Cardano Node at Home guide, where you’ll learn how to set up Ubuntu Server 22.04.2 LTS on a spare PC and run a
cardano-node & cardano-submit-api Docker stack using my GitHub project cardano-node-amd64.
By the time you’ve finished this guide, you’ll have your very own dedicated Cardano Node at home through which you can submit your own transactions to the blockchain.
Installing Ubuntu Server 22.04.2 LTS
You are familiar with Linux or Unix-based operating systems and are at least somewhat comfortable working on a command line.
You have a basic understanding of what Docker and Containers are.
You are building your node on a spare PC, and know the hardware well enough to make basic boot config changes (booting from USB Flash Devices, setting default boot devices, etc.)
Virtual Machines (VMs) are out of scope for this guide, but it’s entirely possible to follow along. The example machine I’m building along with this guide is a VM.
Your home network provides DHCP-assigned addresses.
Optional, but convenient: Your router provides DNS services to your network (i.e., you can ping other computers on your local network by hostname).
A spare PC with a keyboard and a monitor or a VM.
Recommended configuration is at least 2 CPU cores (or vCPUs), with at least 16GB RAM.
This should be an AMD64-based processor (i.e., not ARM-based like Raspberry Pi)
1 Internal SSD or HDD, 250GB or larger
For ease of setup, the device should have only one internal SSD or HDD. This drive will be erased during installation of Ubuntu Server!
A copy of Ubuntu Server 22.04.2 LTS installer on a USB flash drive (download the ISO here)
A wired network connection for your new node.
Connect your system to the network, connect your monitor & keyboard, then boot from your USB Flash Drive.
After your system boots from the installer, select Try or Install Ubuntu Server from the menu by hitting Enter.
Language & Keyboard Layout Selection
Now, choose English (or your preferred language) from the list and hit Enter.
You may be prompted to update to the new installer. Use the up arrow to highlight Update to the new installer, then hit Enter.
Select your keyboard layout. Use the arrow keys to navigate. Space engages the drop-down menus. After your selections are made, or to accept the defaults, use the Tab key until Done is highlighted, then hit Enter.
Installation Type Selection
Hit Enter to choose Done. We’ll use the default of Ubuntu Server here.
You should have received a DHCP address from your network, which is fine for now. Make note of the IP address, you’ll need this later. Hit Done.
For Proxy address, if you have a proxy server enter it here; if not, just hit Enter to select Done. If you have no idea what a proxy server is, you don’t have one. 🙃
Hit Enter to select the default mirror.
Use the Tab key to highlight Done here, then hit Enter.
We’re going to use the default, which is to use 100% of the disk we’re installing on. If you have more than one disk in your machine, you’ll see multiple disks. Select the correct disk, then highlight Done and hit enter.
Hit Enter here to select Done, accepting the defaults.
Use the Down arrow key to highlight Continue, then hit Enter. This action will overwrite anything on the disk, so be certain you’re ok with wiping that hard drive!
Now, we’ll enter our information, using the tab key to navigate between fields:
For Your name, this can be anything you’d like. I used Cardano Node for mine.
For Your server’s name, this should be lowercase, alphanumeric, with no spaces. The only special character allowed is a hyphen/dash ( – ). I used cardano01.
In Pick a username, this will be your login name. I used cardano. This can be anything you’d like, but stick to all lowercase and no spaces.
Finally, when you Choose a password and Confirm your password, choose something long and secure (alphanumeric, mixed case, special characters, etc.)
If prompted to upgrade to Ubuntu Pro, just hit Enter to continue. We’ll skip configuring Ubuntu Pro for now.
Highlight Done with the Tab key, then hit Enter.
If prompted to upgrade to Ubuntu Pro, just hit Enter to continue. We’ll skip configuring Ubuntu Pro for now.
OpenSSH Server & Additional Packages
Now, on this screen, we want to install OpenSSH Server, so hit the Spacebar, and you’ll see an
X next to Install OpenSSH server, as shown below. Now use the Tab key to highlight Done and hit Enter.
Use the Tab key to highlight Done and hit Enter. We’ll manually install the packages we need later.
System Install & Update Process
Now, you’ll see some status messages pass by:
After a few moments, you’ll see Cancel update and reboot at the bottom. Let’s wait until the updates have completed. This could take a few minutes.
Rebooting the System
When the bottom of the screen changes to Reboot Now, use the Tab key to highlight Reboot Now, then hit Enter.
When the reboot is near complete, you’ll see a message requesting you to hit enter after removing the installation medium (the USB Flash Drive, if used). If you’re installing on a VM, just hit Enter. If you’re installing from a USB Flash Drive, disconnect that, then hit Enter.
Logging into the Server
The system will continue reloading, and you’ll see a lot of status messages like the ones above flash by. Once you get to the login screen shown below, log in with the username and password you created in Step 16.
If you do not see the login screen below after a few minutes, and nothing on the screen has changed, hit enter a few times, and you should see a login prompt.
Log in using the credentials you created in User Configuration.
Once logged in, you should be at a non-privileged user prompt (
You’ll probably have additional updates available, as you can see in the image above just a few lines above the prompt.
To install updates, type
sudo apt update && sudo apt -y full-upgrade and hit Enter. You’ll be prompted for your password, so enter that, then hit Enter again.
If you see a screen like the one below, just use Tab until you get to Ok, then hit Enter.
After updates are complete, you’ll be dropped back to the prompt (
One Final Reboot!
sudo reboot now and hit Enter (enter your login password if prompted).
Congratulations, you’ve finished installing Ubuntu Server!
Installing Docker & Additional Packages
We'll be using Docker to run our cardano-node, so first, we need to install Docker and a few additional packages to help out with managing Docker.
To install docker, follow the steps using the commands below.
curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh
TIP: You can preview the steps the script will perform by appending
--dry-run to the end of the second command above.
When the Docker installation is complete, you'll see the results and a new command line.
Install Additional Packages
Now that Docker is installed let's install docker-compose and a couple of other packages. Hit Y to accept the install when prompted. The additional packages are docker-compose (for managing our stack), net-tools & dnsutils (both handy for troubleshooting), git (for cloning the repository), and wget (for downloading the config files).
sudo apt install docker-compose net-tools dnsutils git wget
If prompted to restart services (bright pink background again), tab down to Ok and hit Enter to continue.
Add User to Docker Group
Finally, we'll add our user account to the
docker user group so we'll be able to execute
docker-compose commands without the use of
USER=$(whoami) sudo usermod -aG docker $USER
Set Up the Node Environment
To make the management of the server a little more organized, we're going to set up a folder structure in our home directory.
Log into your server if you're not already logged in. Make sure you're in your home directory; use
cd ~ to get there.
Create a new directory called
Change to this directory:
Clone the Git Repository
git clone https://github.com/brav0charlie/cardano-node-amd64.git
Change into the new project directory:
Run the Setup Script
Run the included
setup.sh script to set up directories and download the mainnet config files:
This script will create a directory called
data inside the the
cardano-node-amd64 directory. Inside the
data directory, it will create
db inside of that.
Then, it downloads the current mainnet configuration files from the official location, and finally returns you to the project directory.
Verifying the Script's Work
For a quick sanity check, run the command below to verify the config files were downloaded:
You should see output similar to the image below:
Starting the Cardano-Node Docker Stack
In this part, we'll fire up our node for the first time. The initial sync will take the better part of a day, perhaps more on slower machines.
We'll also learn how to monitor the node from the command line using
docker logs and
docker exec so you can watch the progress of your node's sync.
To start the docker-compose stack, first navigate to the cardano-node-amd64 directory:
Once you're in the directory, run the following command to start the
docker-compose up -d
-d flag in the command above is shorthand for "detach," which just means to run the container in the background rather than printing it's output to our console.
Monitoring the Node
When you first start the node, things happen quickly because you don't have any blockchain data downloaded and processed.
Docker Container Logs
To take a look at the logs to see if the node is running or if it threw any errors, use the following command:
docker logs cardano-node -f
-f flag above is shorthand for "follow" which just means to keep printing the logs to the screen as new entries come in.
You'll see a bunch of output scrolling by. If you see messages with magenta tags at the beginning of the line like below, this means your node is downloading blocks and adding them to it's copy of the chain.
To exit from this log console, hit
Ctrl + C on your keyboard.
The gist of the messages above is "the chain has been extended, and the new tip id is at slot ", which indicates that the node is doing its job.
Querying Sync Progress
To check the node's sync status, we can use the
docker exec command to execute
cardano-cli query tip --mainnet inside the container:
docker exec cardano-node cardano-cli query tip --mainnet
The command above tells docker to execute (
docker exec) inside the container cardano-node (
cardano-node), the command
cardano-cli query tip --mainnet.
The output should be JSON formatted text that looks like the image below:
What you're seeing above is a collection of data:
blockis the current block number the node has proccessed to.
epochis the epoch in which the current block occurred in.
erais the era of the chain at that point in time.
hashis the hash of the block.
slotis the slot number in which the block was produced (each slot is 1 second since the time the chain went live).
syncProgressis the node's progress in syncing with the blockchain. When this number reaches 100.00%, the sync is complete, and your node continues to process new blocks as they're distributed.
This sync process took roughly 28 hours on a 2 vCPU AWS Instance (like a dual-core computer) with 16GB RAM, so expect to be waiting for quite some time.
You can run the command every few minutes, the progress moves fast at first, but once you hit about 50%, it slows way down.
Another trick you can use is the
watch -n 30 docker exec cardano-node cardano-cli query tip --mainnet
watch command will run your command every n seconds (the number after
-n), with the most recent results remaining on screen until the next time it's run.
If you get an error saying something to the effect of
watch: command not found, you can install it using
sudo apt update && sudo apt install watch.
Stopping the Node
If you need to stop your node at any time, first change to the project directory:
Then, run the following command to bring down the docker-compose stack:
Note that if you stop the node after some time and later restart it with
docker-compose up -d, the node will take up to 10-15 minutes to catch up and verify the state of part of the chain it's already downloaded.
You'll see messages about opening the Ledger DB and replaying blocks with blue tags in the log output. After a while, you'll see the magenta messages start scrolling again after the node has caught up verifying its previous work.
That’s it for now! The sync will take 28+ hours, so if your node is running, sit back and let it do its thing. Check on it using the commands above.
More Coming Soon!
In the next issue, I’ll cover troubleshooting any problems one might have run into during the process above. We'll send a test transaction using our
I’ll also cover setting up a Grafana monitoring dashboard using Prometheus for easier monitoring of your Cardano Node.