Setup a cardano-node relay in 6 steps

I wrote a howto for setting up a Cardano relay.

This howto is different to some other guides as follows:

  1. The building is done separately (on a different machine) so that the running machine does not require compilers and build dependencies
  2. It encourages the user to not rely on custom scripts to compile, install, and upgrade
  3. Instead it uses the familiar Debian/Ubuntu package manager for installation and upgrades
  4. It should make troubleshooting problems easier since there are no changes to executable paths, library paths, or environment variables and there are no complex scripts that automate things

@COSDpool @rdlrt feel free to modify or use aspects if it is relevant to your documentation efforts.


This is promising & I’ve suggested adding an Appendix section to the outline of our remodelling Stake Pool Course… for material like this that’s useful for growth & further study but not necessarily part of the rigorous procedure for every SPO:

Ummm, every SPO needs to set up a relay.

I get the distinct feeling that there seems to be 3 main issues with the approach I am taking:

  1. I am using the package manager to install and update cardano-node as opposed to using a custom script or manual method
  2. I am setting up everything to use standard filesystem locations for configs, database, binaries and libraries (but with no “pollution of filesystem” because the package manager effectively compartmentalises everything as it does for every other package)
  3. I advise installing only necessities on the running machine (relay) and to have compilers and development toolchain on a different machine (or at least a different account)

The first 2 things make it easier for a novice user and particularly someone who is not very familiar with Linux. The third point does involve a few extra steps on a different machine (or account), but the benefit is simplification of installations/upgrades across multiple machines, as well as some security advantages.

But these are just my opinions. Since the guides are directed at novice users, such an approach makes sense to me.

I am happy to write similar guides about setting up and running a block-producer including all the stake pool operations such as creating the pool keys and certificate. I can also write guides about running each relay and block-producer in virtual machines (kvm on Linux) including the routing and firewalling.

Unfortunately, it is not practical for the package manager to have the user configure filesystem layout at the install stage. If the community has decided that they don’t want to use their package managers, prefer a /opt/cardano filesystem layout with custom user path, and want the development toolchain on their running machines, then I will butt out. Because, I don’t want to work at crossed-purposes with the rest of the community.


on the contrary I think there will come a point in any intelligent SPO’s life when they’re going to need to consider the subjects you are writing about: so I would rather take this opportunity to attract & promote this material as soon as we can come up with a productive way to classify it.

What do other readers & SPOs think of adding (at the end, again: like an Appendix) a Deployment Scenarios section to the draft SPO guide, where we can put material according to these proposed guidelines?

1 Like

I really like your approach of using the standard ways to do things. And it should really have a place in the documentation somewhere (maybe also for other distributions?).

…, but that is not really intuitive. If they are not very familiar with Linux, they will also not know about the Filesystem Hierarchy Standard and only roughly know what their package manager does. Unfortunately.

You could tell them how to use systemctl cat and systemctl edit. That would also be a good replacement for the slightly cumbersome self-defined configuration file/EnvironmentFile construction you are currently using for modifying the port. That way, they could change the layout at will, which might especially be wanted for the huge database, which people might want to put in a better suited place.

I don’t think the community has decided on anything. The non-optional part of the introduction should probably have a few words about the fact that things can be in a lot of different places depending on which method(s) you followed.

I don’t think that not using the package manager of the distribution implies that they build everything anew on each machine. They could, e.g., just copy the binaries around, use the IOG-built binaries in the first place, …

1 Like

I was hoping that someone would produce similar packages for other distributions.

Exactly and they usually don’t want to know either. They just want the executable to work from everywhere. And novices don’t want to do things like modify their users PATH and then wonder why the same command doesn’t work as root or some other user.

Yeah that is a bit of a cludge. I have another document part-written about setting up a block producer which would involve creating a new systemd service file. I wanted a way to allow the user to have a different port number configured and have the default systemd service use it. Can you suggest a better way to do that?

Yes and copy the secp256k1 library files and create the correct symlinks. (The Debian build system compiled this library in to the binaries on my system.)

I changed the systemd service file to the following:

Description=Cardano Node

# Default PORT can be overridden in MY_CARDANO_NODE_CONFIG
ExecStart=sh -c "\
if [ -f ${MY_CARDANO_NODE_CONFIG} ]; then \
  PORT=$$(jq --arg PORT ${PORT} '.port // ($PORT | tonumber)' ${MY_CARDANO_NODE_CONFIG}); \
else \
  PORT=${PORT}; \
fi; \
cardano-node +RTS -N -RTS run \
  --host-addr \
  --port $${PORT} \
  --topology /etc/cardano/mainnet-topology.json \
  --database-path /var/lib/cardano \
  --socket-path /run/cardano/mainnet-node.socket \
  --config /etc/cardano/mainnet-config.json \


It is still a bit cumbersome because systemd doesn’t let you run scripts easily.

This allows people to set their preferred custom port in “my-cardano-node-config.json” file without having to create a new systemd service file. But, it doesn’t matter if this file doesn’t exist because it will default to using port 3001 which seems to be a Cardano “standard”.

If they don’t like that method then it is pretty easy to edit the systemd service file to create a custom version which will override the system-wide version the deb package installs. Note that if you want to run cardano-node as a block producer you will need to create a custom systemd service file anyway because you need to specify your kes and vrf keys as well as your operational certificate.

For example, this is the systemd service file I use for my block producer:

Description=Cardano Node

#ExecStart=cardano-node +RTS -N -I0.1 -Iw43200 -A32M -AL256M -n16m -F0.3 -O20G -M40G -c99 -Mgrace=1G -C0 -RTS run \
ExecStart=cardano-node +RTS -N --nonmoving-gc -RTS run \
  --host-addr "" \
  --port "${PORT}" \
  --socket-path '/run/cardano/mainnet-node.socket' \
  --config "/etc/cardano/mainnet-config.json" \
  --topology "/etc/cardano/mainnet-topology.json" \
  --shelley-kes-key "/etc/cardano/private/kes.skey" \
  --shelley-vrf-key "/etc/cardano/private/vrf.skey" \
  --shelley-operational-certificate "/etc/cardano/private/node.cert" \
  --database-path "/var/lib/cardano"


Instructions for building cardano-node as a deb updated to version 1.35.7.

Also the Terminada deb repository now has the 1.35.7 binary debs for both arm64 and amd64 systems. If you don’t want to compile your own debs and want to trust someone called “Terminada”, then you can simply use my compiled versions by adding the Terminada repository to your apt sources list:

wget -O- | gpg --dearmor | sudo tee /usr/share/keyrings/ > /dev/null
echo "deb [signed-by=/usr/share/keyrings/] ./" | sudo tee /etc/apt/sources.list.d/
sudo apt update

Followed installing the deb:

apt install cardano-node
1 Like