This document outlines one way to build the cardano-node software into Debian packages. Building the software as deb packages makes it easier to install on any Debian or Ubuntu system and have the package management system take care of everything.
These are not official deb packages and this document does not do things the official Debian/Ubuntu way. Furthermore, these deb packages do not deliver the proper copyright documents or any manuals.
These deb packages will install the software in the following standard locations:
- Libraries are placed in /usr/lib/
- Executables are placed in /usr/bin/
- Configuration files are placed in /etc/cardano/
- Cardano blockchain database is stored in /var/lib/cardano
- Systemd service file is placed in /lib/systemd/system/
- See wiki article: Getting cardano-node: Building from source
- Review version history of the corresponding markdown file: https://github.com/cardano-foundation/developer-portal/blob/staging/docs/get-started/infrastructure/node/installing-cardano-node.md
- Click "History" in top right, then click any recent commits to see what changes have been made. If no significant changes then continue.
I usually create a virtual machine for building software and do everything on it. This allows me to keep everything separated from my desktop PC.
I also create a separate user ('builder') for building. This is advisable, even if you choose to build on your desktop PC, so that the installation of any local compilers, or any specific configurations, won't interfere with anything in your normal user account.
sudo adduser --gecos '' --disabled-password builder
Install build dependencies and some extra requirements
sudo apt install --assume-yes build-essential fakeroot devscripts debhelper autoconf-archive d-shlibs pkg-kde-tools git curl automake pkg-config libffi-dev libgmp-dev libssl-dev libtinfo-dev libsystemd-dev zlib1g-dev make jq pandoc libncursesw5 libtool autoconf libncurses-dev libncurses5 libnuma-dev liblmdb-dev binutils-gold libsnappy-dev protobuf-compiler liburing-dev
Optionally install llvm and set cc and c++ to use clang
sudo apt install llvm clang
sudo update-alternatives --install /usr/bin/cc cc /usr/bin/clang 100
sudo update-alternatives --install /usr/bin/c++ c++ /usr/bin/clang++ 100
Ubuntu users might need to skip the previous optional step if their Ubuntu version of clang doesn't support optimization flag '-ffat-lto-objects'. Revert the previous changes with:
sudo apt purge llvm clang
sudo apt autoremove
Ubuntu users may need to manually install libssl1.1 if it is not on their system:
wget http://security.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2.22_amd64.deb
sudo dpkg -i libssl1.1_1.1.1f-1ubuntu2.22_amd64.deb
Make sure you have built all these to deb files first:
- See: Build IOG specified version of libsodium as a deb package
- See: Build IOG specified version of libsecp256k1 as a deb package
- See: Build IOG specified version of libblst as a deb package
If you have put these dependency debs into a local repository then you can simply use apt to install them:
apt install libsodium-dev-iog libsecp256k1-dev-iog libblst-iog
Otherwise use dpkg to install them:
dpkg -i libsodium23-iog_1.0.18_amd64.deb libsodium-dev-iog_1.0.18_amd64.deb
dpkg -i libsecp256k1-2-iog_0.3.2_amd64.deb libsecp256k1-dev-iog_0.3.2_amd64.deb
dpkg -i libblst-iog_0.3.14_amd64.deb
Switch to your builder account
sudo su - builder
The rest of this document assumes you are using your 'builder' account:
builder@build:~$
curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | sh
Select 'N' to everything when asked. We will set up path manually.
The following is an example transcript:
ghcup installs only into the following directory, which can be removed anytime:
/home/builder/.ghcupPress ENTER to proceed or ctrl-c to abort.
Do you want ghcup to automatically add the required PATH variable to "/root/.bashrc"?
[P] Yes, prepend [A] Yes, append [N] No [?] Help (default is "P").
NDo you want to install haskell-language-server (HLS)?
[Y] Yes [N] No [?] Help (default is "N").
NDo you want to install stack?
[Y] Yes [N] No [?] Help (default is "N").
NSystem requirements
Please install the following distro packages: build-essential curl libffi-dev libffi7 libgmp-dev libgmp10 libncurses-dev libncurses5 libtinfo5Press ENTER to proceed or ctrl-c to abort.
These 'system requirements' packages should already have been installed above so just press enter.
echo '[[ ":$PATH:" != *":$HOME/.ghcup/bin:"* ]] && PATH="$HOME/.ghcup/bin:$PATH"' >> ${HOME}/.bashrc
echo '[[ ":$PATH:" != *":$HOME/.cabal/bin:"* ]] && PATH="$HOME/.cabal/bin:$PATH"' >> ${HOME}/.bashrc
echo 'export PATH' >> ${HOME}/.bashrc
source ${HOME}/.bashrc
Check versions
ghcup --version
cabal --version
Use ghcup tui to view which version of ghc and cabal are available. Then choose which versions to install and set as default.
Previously built dependencies are stored in ${HOME}/.cabal/store/
To force the haskell compiler to rebuild all the dependencies from scratch, remove this directory and all its subdirectories with:
rm -rf ${HOME}/.cabal/store
See: https://github.com/intersectMBO/cardano-node
Or from the command line with:
CARDANO_NODE_VERSION="$(curl -s https://api.github.com/repos/intersectMBO/cardano-node/releases/latest | jq -r .tag_name)"
echo "Latest CARDANO_NODE_VERSION is: ${CARDANO_NODE_VERSION}"
You can also check available tags at: https://github.com/IntersectMBO/cardano-node/tags
# 1. Latest CARDANO_NODE_VERSION
CARDANO_NODE_VERSION="$(curl -s https://api.github.com/repos/intersectMBO/cardano-node/releases/latest | jq -r .tag_name)"
# 2. IOHKNIX_VERSION
IOHKNIX_VERSION="$(curl https://raw.githubusercontent.com/IntersectMBO/cardano-node/$CARDANO_NODE_VERSION/flake.lock | jq -r '.nodes.iohkNix.locked.rev')"
# 3. Required versions
# Fetch iohk-nix flake.lock, read SODIUM_VERSION SECP256K1_VERSION BLST_VERSION
read -r -d '' SODIUM_VERSION SECP256K1_VERSION BLST_VERSION < <(
curl -s https://raw.githubusercontent.com/input-output-hk/iohk-nix/$IOHKNIX_VERSION/flake.lock |
jq -r '
.nodes.sodium.original.rev,
.nodes.secp256k1.original.ref,
.nodes.blst.original.ref
'
)
# 4. Currently installed versions
current_SODIUM_VERSION="$(dpkg -s libsodium-dev-iog | grep "built from commit:" | awk '{print $NF}')"
current_SECP256K1_VERSION="$(pkg-config --modversion libsecp256k1 2>/dev/null)"
current_BLST_VERSION="$(pkg-config --modversion libblst 2>/dev/null)"
# 5. Helper for formatted output
print_status() {
local label="${1:-}" required="${2:-}" current="${3:-}"
[[ "$required" == "$current" ]] || {
echo "Required $label $required [❌] (Installed: $current)"
return 1
}
echo "Required $label $required [✅]"
return 0
}
# 6. Verify required versions
FAIL=0
echo ""
echo "=================================================================="
echo "= cardano-node dependency verification ="
echo "=================================================================="
echo "cardano Node version: $CARDANO_NODE_VERSION"
echo "iohk-nix version: $IOHKNIX_VERSION"
echo "------------------------------------------------------------------"
print_status "libsodium version: " "$SODIUM_VERSION" "$current_SODIUM_VERSION" || FAIL=1
print_status "libsecp256k1 version:" "${SECP256K1_VERSION#v}" "$current_SECP256K1_VERSION" || FAIL=1
print_status "libblst version: " "${BLST_VERSION#v}" "$current_BLST_VERSION" || FAIL=1
echo "------------------------------------------------------------------"
if (( FAIL == 0 )); then
echo "✅ All installed dependencies matched required versions"
else
echo "❌ MISMATCHED DEPENDENCY. Please install libraries to match required versions."
fi
echo "=================================================================="
The following sequence of commands will remove and recreate the "${HOME}/src/cardano-node" directory. Familiarise yourself with the following commands before running them. You can simply copy and paste the entire list of commands below into a bash terminal to run them in sequence.
Nb. Ensure ${CARDANO_NODE_VERSION}" variable has been set either manually or by using the previous command.
deb_build_instructions_repo='https://github.com/TerminadaPool/cardano-node-debian.git'
cardano_node_repo='https://github.com/IntersectMBO/cardano-node.git'
package='cardano-node'
basedir="${HOME}/src/${package}"
mkdir -p "${basedir}"
cd "${basedir}"
rm -rf "${package}-${CARDANO_NODE_VERSION}"
git clone "${cardano_node_repo}" "cardano-node-${CARDANO_NODE_VERSION}"
cd "cardano-node-${CARDANO_NODE_VERSION}"
git fetch --all --recurse-submodules --tags
git checkout "tags/${CARDANO_NODE_VERSION}"
git clone "${deb_build_instructions_repo}" debian
DEB_BUILD_OPTIONS="noautodbgsym" debuild --prepend-path "$HOME/.cabal/bin:$HOME/.ghcup/bin" -us -uc -b
unset deb_build_instructions_repo cardano_node_repo package basedir
Your debs will be produced in the parent directory: "${HOME}/src/cardano-node/". They will be named something like:
cardano-cli_10.1.4_amd64.deb cardano-node_10.1.4_amd64.deb cardano-submit-api_10.1.4_amd64.deb
Put these files in your own local debian repository and install them on every machine required using apt.
- The ghc and cabal versions used for compilation are configured in rules file.
- cabal.project.local is also configured in rules file.
- Both cardano-node and cardano-cli packages are configured to depend upon the IOG specified versions of libsodium (libsodium23-iog) and libsecp256k1 (libsecp256k1-2-iog). See: control file.
- If cardano-node deb package is purged from the system then unaltered configuration files will be removed as well as /etc/cardano directory if it is subsequently empty. However, the 'cardano' user will be left on the system. See: cardano-node.postrm.
- There are example configuration files installed to '/etc/cardano/{mainnet,preprod,preview}/pooltool-api-key'. The script cn-monitor-block-delay can use these files to obtain the "Pooltool Api Key" without obtaining such information from the command line where it is visible to tools like 'ps'.
- The systemd cardano-node service file will optionally configure its $SERVICE_PORT from /etc/cardano/{mainnet,preprod,preview}/service-port if such file contains a SERVICE_PORT=VALUE line (Eg: SERVICE_PORT=3001).
- There are some additional simple tools in the bin subdirectory which get installed to /usr/bin/ on the system.
- Expect to see lintian errors like the following at the end of the build process:
E: cardano-cli: embedded-library libyaml [usr/bin/cardano-cli]
E: cardano-cli: embedded-library libyaml [usr/bin/cardano-submit-api]
E: cardano-node: embedded-library libyaml [usr/bin/cardano-node]
E: cardano-cli-dbgsym: unpack-message-for-deb-data Output from 'readelf --all --wide usr/lib/debug/.build-id/38/6c97fd1b0d66cdf82ce266e02753ec53350991.debug' is not valid UTF-8
E: cardano-cli-dbgsym: unpack-message-for-deb-data Output from 'readelf --all --wide usr/lib/debug/.build-id/74/a3012a640a238f66de1826f93f0a77b7dcb007.debug' is not valid UTF-8
E: cardano-cli-dbgsym: unpack-message-for-deb-data Output from 'readelf --all --wide usr/lib/debug/.build-id/fa/db822a91370d4704149b863a99d11587429f8c.debug' is not valid UTF-8
E: cardano-node-dbgsym: unpack-message-for-deb-data Output from 'readelf --all --wide usr/lib/debug/.build-id/5b/47687ea24048b81acfe15296947430f48b617e.debug' is not valid UTF-8
W: cardano-cli-dbgsym: debug-file-with-no-debug-symbols [usr/lib/debug/.build-id/38/6c97fd1b0d66cdf82ce266e02753ec53350991.debug]
W: cardano-cli-dbgsym: debug-file-with-no-debug-symbols [usr/lib/debug/.build-id/74/a3012a640a238f66de1826f93f0a77b7dcb007.debug]
W: cardano-cli-dbgsym: debug-file-with-no-debug-symbols [usr/lib/debug/.build-id/fa/db822a91370d4704149b863a99d11587429f8c.debug]
W: cardano-node-dbgsym: debug-file-with-no-debug-symbols [usr/lib/debug/.build-id/5b/47687ea24048b81acfe15296947430f48b617e.debug]
W: cardano-cli: hardening-no-pie [usr/bin/bech32]
W: cardano-cli: hardening-no-pie [usr/bin/cardano-cli]
W: cardano-cli: hardening-no-pie [usr/bin/cardano-submit-api]
W: cardano-node: hardening-no-pie [usr/bin/cardano-node]
W: cardano-cli: no-manual-page [usr/bin/bech32]
W: cardano-cli: no-manual-page [usr/bin/cardano-cli]
W: cardano-cli: no-manual-page [usr/bin/cardano-submit-api]
W: cardano-cli: no-manual-page [usr/bin/cn-date-to-slot]
W: cardano-cli: no-manual-page [usr/bin/cn-slot-to-date]
W: cardano-node: no-manual-page [usr/bin/cardano-node]
W: cardano-node: no-manual-page [usr/bin/cn-leaderlog]
W: cardano-node: no-manual-page [usr/bin/cn-monitor-block-delay]
W: cardano-node: no-manual-page [usr/bin/cn-update-topology]
debuild switches:
- -b: build binary packages only
- -uc: No signing of chainlog
- -us: No signing of source code