Setup Nodo de Cardano

Escrito por Yovany

Guía de Instalación: Nodo Cardano 10.6.2 en Ubuntu 22.04.5 LTS

¿Por qué esta guía?

La motivación detrás de esta guía es poder desplegar un pool de Cardano. Si bien hay muchas guías de este proceso en la red, no encontré una actualizada que funcionara de principio a fin; siempre había algún paso en el que encontraba un error que me impedía continuar, o en otras ocasiones, aun cuando todo el proceso se ejecutaba de forma correcta, el nodo no lograba sincronizar. Esto se debe a que hay aspectos que van cambiando con el transcurso del tiempo y las guías no se actualizan de forma integral para incorporar los cambios necesarios. Es por esto que decidí documentar este proceso, incluyendo los pasos que muchas guías omitían y con las versiones actualizadas de las librerías.
Este documento está basado en la guía de CoinCashew para la configuración de un pool de Cardano, por lo que muchos de los pasos serán similares; sin embargo, si son observadores, podrán notar las diferencias que hay entre ambos procesos.

Las caracteristicas de la instalación son las siguientes:

Campo Detalle
Sistema Operativo Ubuntu 22.04.5 LTS (Jammy Jellyfish)
Cliente Cardano cardano-node 10.6.2
Método de instalación Compilación desde fuente (GHC + Cabal)
Redes soportadas Mainnet / Preprod / Preview
Arquitectura x86_64-linux
Repositorio oficial github:IntersectMBO/cardano-node

Índice

  1. Introducción
  2. Requisitos del sistema
  3. Preparar Ubuntu 22.04.5
  4. Hardening de Ubuntu Server 22.04.5
  5. Crear usuario cardano
  6. Instalar GHCup, GHC y Cabal
  7. Instalar dependencias del sistema
  8. Configurar variables de entorno
  9. Compilar cardano-node 10.6.2
  10. Descargar archivos de configuración
  11. Configurar y ejecutar el nodo
  12. Configurar servicio systemd
  13. Verificación y monitoreo
  14. Monitoreo con gLiveView
  15. Actualización del nodo
  16. Recursos adicionales

1. Introducción

Esta guía sigue el estilo de CoinCashew para instalar cardano-node compilando desde el código fuente usando GHC y Cabal. Este método da control total sobre los binarios y es el enfoque tradicional usado por la mayoría de stake pool operators.

¿Por qué compilar desde fuente?

  • Control total sobre el binario instalado
  • No depende de gestores de paquetes externos
  • Método probado y documentado por la comunidad desde 2021
  • Compatible con el flujo de trabajo de CoinCashew

Nota: Esta guía asume que tienes acceso de superusuario (sudo) y conexión a Internet. La compilación inicial tarda entre 20 y 40 minutos dependiendo del hardware.


2. Requisitos del sistema

Componente Mínimo Recomendado
CPU 2 núcleos x86_64 4+ núcleos x86_64
RAM (backend OnDisk) 8 GB 16 GB o más
RAM (backend InMemory) 24 GB 32 GB o más
Almacenamiento 150 GB SSD 350 GB SSD NVMe
Sistema Operativo Ubuntu 22.04 LTS Ubuntu 22.04.5 LTS
Ancho de banda 1 Mbps 10+ Mbps

Nota sobre RAM: Desde la versión 10.6.x el nodo soporta dos backends de ledger. El backend OnDisk requiere 8 GB de RAM; el backend InMemory (más rápido) requiere 24 GB mínimo.


3. Preparar Ubuntu 22.04.5

Actualiza el sistema e instala las dependencias base necesarias:

# Actualizar repositorios y paquetes del sistema
sudo apt update && sudo apt upgrade -y

# Instalar herramientas esenciales
sudo apt install -y curl wget git build-essential \
    libffi-dev libgmp-dev libssl-dev libtinfo-dev \
    libsystemd-dev zlib1g-dev make g++ jq xz-utils \
    libnuma-dev libtool autoconf pkg-config llvm

⚠️ Aviso: Si usas un servidor remoto (VPS), asegúrate de tener configurado un usuario no-root con permisos sudo antes de continuar.


4. Hardening de Ubuntu Server 22.04.5

Omití esta sección por el momento, ya que buscaba hacer funcionar el nodo antes de implementar las medidas de seguridad, con la intención de descartar que los problemas presentados inicialmente se debieran a una mala configuración. Por lo tanto, dejaremos esta sección para más adelante.


5. Crear usuario cardano

Por seguridad, el nodo corre bajo un usuario dedicado sin privilegios de root.

# Crear el usuario cardano con directorio home y shell bash
sudo useradd -m -s /bin/bash cardano

# Añadir al grupo sudo — solo si se requiere sudo puntual
sudo usermod -aG sudo cardano

# Establecer contraseña para el usuario cardano
sudo passwd cardano
# Se pedirá ingresar y confirmar la nueva contraseña

Cambiar al usuario cardano

A partir de este punto, todos los pasos de instalación y configuración se ejecutan como el usuario cardano:

sudo -u cardano -i
# El prompt cambiará a: cardano@hostname:~$

echo $HOME
# Salida esperada: /home/cardano

6. Instalar GHCup, GHC y Cabal

GHCup es el instalador oficial del toolchain de Haskell. Instala la versión de GHC requerida por cardano-node 10.6.2:

# Instalar GHCup
curl -sSf https://get-ghcup.haskell.org | \
    BOOTSTRAP_HASKELL_NONINTERACTIVE=1 \
    BOOTSTRAP_HASKELL_GHC_VERSION=9.6.7 \
    BOOTSTRAP_HASKELL_CABAL_VERSION=3.12.1.0 \
    BOOTSTRAP_HASKELL_INSTALL_STACK=0 \
    BOOTSTRAP_HASKELL_INSTALL_HLS=0 \
    sh

Recarga el entorno:

source ~/.bashrc
source ~/.ghcup/env

Verifica las versiones instaladas:

ghc --version
# Salida esperada: The Glorious Glasgow Haskell Compilation System, version 9.6.7

cabal --version
# Salida esperada: cabal-install version 3.10.x.x

7. Instalar dependencias del sistema

cardano-node requiere libsodium y libsecp256k1 compiladas desde fuente:

libsodium

mkdir -p ~/git
cd ~/git
git clone https://github.com/input-output-hk/libsodium
cd libsodium
git checkout dbb48cc
./autogen.sh
./configure
make
sudo make install

libsecp256k1

cd ~/git
git clone --depth 1 --branch v0.3.2 https://github.com/bitcoin-core/secp256k1
cd secp256k1
./autogen.sh
./configure --enable-module-schnorrsig --enable-experimental
make
make check
sudo make install

libblst

cd ~/git
git clone https://github.com/supranational/blst
cd blst
git checkout v0.3.14
./build.sh
cat > libblst.pc << EOF
prefix=/usr/local
exec_prefix=\${prefix}
libdir=\${exec_prefix}/lib
includedir=\${prefix}/include

Name: libblst
Description: Multilingual BLS12-381 signature library
URL: https://github.com/supranational/blst
Version: 0.3.14
Libs: -L\${libdir} -lblst
Cflags: -I\${includedir}
EOF
sudo cp libblst.pc /usr/local/lib/pkgconfig/
sudo cp bindings/blst_aux.h bindings/blst.h bindings/blst.hpp /usr/local/include/
sudo cp libblst.a /usr/local/lib/
sudo chmod u=rw,go=r /usr/local/lib/libblst.a

Actualiza el cache de librerías:

sudo ldconfig

8. Configurar variables de entorno

Añade las variables de entorno al perfil del usuario. Incluyen las rutas de las librerías compiladas y las rutas del nodo:

cat >> ~/.bashrc << 'EOF'

# Configurar rutas para que el compilador encuentre las librerías libsodium, libsecp256k1 y blst
export LD_LIBRARY_PATH="/usr/local/lib:$LD_LIBRARY_PATH"
export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH"
# Ruta base para los archivos de configuración y scripts del nodo Cardano
export NODE_HOME="$HOME/cardano-my-node"
# Red de Cardano donde opera el nodo
export NODE_CONFIG="mainnet"
# Ruta del archivo socket del nodo Cardano
export CARDANO_NODE_SOCKET_PATH="$NODE_HOME/db/socket"
EOF

source ~/.bashrc

9. Compilar cardano-node 10.6.2

cd ~/git
git clone https://github.com/IntersectMBO/cardano-node.git
cd cardano-node
git fetch --all --recurse-submodules --tags

# Cambiar al tag de la versión deseada
git checkout tags/10.6.2

# Actualizar cabal e instalar dependencias
cabal update

# Ajustar configuración del proyecto para GHC 9.6.7
cabal configure -O0 -w ghc-9.6.7

# Compilar (tarda entre 20 y 40 minutos)
cabal build all
cabal build cardano-cli

Copia los binarios al directorio de sistema:

sudo cp -p "$(./scripts/bin-path.sh cardano-node)" /usr/local/bin/cardano-node
sudo cp -p "$(./scripts/bin-path.sh cardano-cli)" /usr/local/bin/cardano-cli

Verifica que los binarios están disponibles:

cardano-node --version
cardano-cli --version

# Salida esperada:
# cardano-node 10.6.2 - linux-x86_64 - ghc-9.6
# cardano-cli 10.6.2 - linux-x86_64 - ghc-9.6

ℹ️ Info: El proceso de compilación puede tardar entre 20 y 40 minutos. Si hay errores de memoria durante la compilación, agrega -j1 al comando cabal para usar un solo core: cabal build all -j1.


10. Descargar archivos de configuración

Cada red usa los mismos nombres de archivo, por lo que deben ir en directorios separados. Crea la estructura completa desde el inicio:

# Crear directorios separados por red
mkdir -p ~/cardano-my-node/{mainnet,preprod,preview}/{config,db,socket}

La estructura quedará así:

~/cardano-my-node/
├── mainnet/
│   ├── config/
│   ├── db/
│   └── socket/
├── preprod/
│   ├── config/
│   ├── db/
│   └── socket/
└── preview/
    ├── config/
    ├── db/
    └── socket/

Descarga los archivos de la red que vayas a usar:

Mainnet (red principal)

BASE_URL="https://book.world.dev.cardano.org/environments/mainnet"
for file in config.json topology.json byron-genesis.json \
            shelley-genesis.json alonzo-genesis.json \
            conway-genesis.json checkpoints.json \
            peer-snapshot.json; do
  wget -q ${BASE_URL}/${file} -P ~/cardano-my-node/mainnet/config
  echo "✓ Descargado: ${file}"
done

Preprod (testnet recomendada para desarrollo)

BASE_URL="https://book.world.dev.cardano.org/environments/preprod"
for file in config.json topology.json byron-genesis.json \
            shelley-genesis.json alonzo-genesis.json \
            conway-genesis.json checkpoints.json \
            peer-snapshot.json; do
  wget -q ${BASE_URL}/${file} -P ~/cardano-my-node/preprod/config
  echo "✓ Descargado: ${file}"
done

Preview (testnet para nuevas features)

BASE_URL="https://book.world.dev.cardano.org/environments/preview"
for file in config.json topology.json byron-genesis.json \
            shelley-genesis.json alonzo-genesis.json \
            conway-genesis.json checkpoints.json \
            peer-snapshot.json; do
  wget -q ${BASE_URL}/${file} -P ~/cardano-my-node/preview/config
  echo "✓ Descargado: ${file}"
done
Red Flag Magic ID Puerto Uso
Mainnet --mainnet 3001 Producción, ADA real
Preprod --testnet-magic 1 1 3002 Pruebas estables
Preview --testnet-magic 2 2 3003 Pruebas de nuevas features

⚠️ Aviso: Para pruebas y desarrollo, usa preprod o preview. Nunca uses ADA real en testnet.


11. Configurar y ejecutar el nodo

Crea un script de inicio por red:

Script para Mainnet

cat > ~/cardano-my-node/mainnet/start-node.sh << 'EOF'
#!/usr/bin/env bash
NODE_DIR="${HOME}/cardano-my-node/mainnet"
export CARDANO_NODE_SOCKET_PATH="${NODE_DIR}/socket/node.socket"

/usr/local/bin/cardano-node run \
  --topology      "${NODE_DIR}/config/topology.json" \
  --database-path "${NODE_DIR}/db" \
  --socket-path   "${CARDANO_NODE_SOCKET_PATH}" \
  --config        "${NODE_DIR}/config/config.json" \
  --port          3001
EOF
chmod +x ~/cardano-my-node/mainnet/start-node.sh

Script para Preprod

cat > ~/cardano-my-node/preprod/start-node.sh << 'EOF'
#!/usr/bin/env bash
NODE_DIR="${HOME}/cardano-my-node/preprod"
export CARDANO_NODE_SOCKET_PATH="${NODE_DIR}/socket/node.socket"

/usr/local/bin/cardano-node run \
  --topology      "${NODE_DIR}/config/topology.json" \
  --database-path "${NODE_DIR}/db" \
  --socket-path   "${CARDANO_NODE_SOCKET_PATH}" \
  --config        "${NODE_DIR}/config/config.json" \
  --port          3002
EOF
chmod +x ~/cardano-my-node/preprod/start-node.sh

Script para Preview

cat > ~/cardano-my-node/preview/start-node.sh << 'EOF'
#!/usr/bin/env bash
NODE_DIR="${HOME}/cardano-my-node/preview"
export CARDANO_NODE_SOCKET_PATH="${NODE_DIR}/socket/node.socket"

/usr/local/bin/cardano-node run \
  --topology      "${NODE_DIR}/config/topology.json" \
  --database-path "${NODE_DIR}/db" \
  --socket-path   "${CARDANO_NODE_SOCKET_PATH}" \
  --config        "${NODE_DIR}/config/config.json" \
  --port          3003
EOF
chmod +x ~/cardano-my-node/preview/start-node.sh

ℹ️ Info: Los scripts usan la ruta absoluta /usr/local/bin/cardano-node ya que el binario fue copiado ahí durante la compilación. Esto evita problemas de PATH con systemd.


12. Configurar servicio systemd

Crea un servicio systemd por cada red que vayas a operar:

Servicio Mainnet

sudo tee /etc/systemd/system/cardano-node-mainnet.service > /dev/null << 'EOF'
# The Cardano Node service (part of systemd)
# file: /etc/systemd/system/cardano-node-mainnet.service

[Unit]
Description       = Cardano Node Service
Wants             = network-online.target
After             = network-online.target

[Service]
User              = cardano
Type              = simple
WorkingDirectory  = /home/cardano/cardano-my-node/mainnet
ExecStart         = /bin/bash -c '/home/cardano/cardano-my-node/mainnet/start-node.sh'
KillSignal        = SIGINT
RestartKillSignal = SIGINT
TimeoutStopSec    = 300
LimitNOFILE       = 32768
Restart           = always
RestartSec        = 5
SyslogIdentifier  = cardano-node-mainnet

[Install]
WantedBy          = multi-user.target
EOF

Servicio Preprod

sudo tee /etc/systemd/system/cardano-node-preprod.service > /dev/null << 'EOF'
# The Cardano Node service (part of systemd)
# file: /etc/systemd/system/cardano-node-preprod.service

[Unit]
Description       = Cardano Node Service
Wants             = network-online.target
After             = network-online.target

[Service]
User              = cardano
Type              = simple
WorkingDirectory  = /home/cardano/cardano-my-node/preprod
ExecStart         = /bin/bash -c '/home/cardano/cardano-my-node/preprod/start-node.sh'
KillSignal        = SIGINT
RestartKillSignal = SIGINT
TimeoutStopSec    = 300
LimitNOFILE       = 32768
Restart           = always
RestartSec        = 5
SyslogIdentifier  = cardano-node-preprod

[Install]
WantedBy          = multi-user.target
EOF

Servicio Preview

sudo tee /etc/systemd/system/cardano-node-preview.service > /dev/null << 'EOF'
# The Cardano Node service (part of systemd)
# file: /etc/systemd/system/cardano-node-preview.service

[Unit]
Description       = Cardano Node Service
Wants             = network-online.target
After             = network-online.target

[Service]
User              = cardano
Type              = simple
WorkingDirectory  = /home/cardano/cardano-my-node/preview
ExecStart         = /bin/bash -c '/home/cardano/cardano-my-node/preview/start-node.sh'
KillSignal        = SIGINT
RestartKillSignal = SIGINT
TimeoutStopSec    = 300
LimitNOFILE       = 32768
Restart           = always
RestartSec        = 5
SyslogIdentifier  = cardano-node-preview

[Install]
WantedBy          = multi-user.target
EOF

Habilita e inicia los servicios:

sudo systemctl daemon-reload

# Mainnet
sudo systemctl enable cardano-node-mainnet
sudo systemctl start cardano-node-mainnet

# Preprod
sudo systemctl enable cardano-node-preprod
sudo systemctl start cardano-node-preprod

# Preview
sudo systemctl enable cardano-node-preview
sudo systemctl start cardano-node-preview

Comandos útiles por red

# Ver estado
sudo systemctl status cardano-node-mainnet
sudo systemctl status cardano-node-preprod
sudo systemctl status cardano-node-preview

# Ver logs en tiempo real
journalctl -fu cardano-node-mainnet
journalctl -fu cardano-node-preprod
journalctl -fu cardano-node-preview

# Iniciar
sudo systemctl start cardano-node-mainnet
sudo systemctl start cardano-node-preprod
sudo systemctl start cardano-node-preview

# Detener
sudo systemctl stop cardano-node-mainnet
sudo systemctl stop cardano-node-preprod
sudo systemctl stop cardano-node-preview

# Reiniciar
sudo systemctl restart cardano-node-mainnet
sudo systemctl restart cardano-node-preprod
sudo systemctl restart cardano-node-preview

# Recargar configuración del servicio (después de editar el .service)
sudo systemctl daemon-reload
sudo systemctl restart cardano-node-mainnet
sudo systemctl restart cardano-node-preprod
sudo systemctl restart cardano-node-preview

13. Verificación y monitoreo

Consultar estado de sincronización

# Mainnet
export CARDANO_NODE_SOCKET_PATH="${HOME}/cardano-my-node/mainnet/socket/node.socket"
cardano-cli query tip --mainnet

# Preprod
export CARDANO_NODE_SOCKET_PATH="${HOME}/cardano-my-node/preprod/socket/node.socket"
cardano-cli query tip --testnet-magic 1

# Preview
export CARDANO_NODE_SOCKET_PATH="${HOME}/cardano-my-node/preview/socket/node.socket"
cardano-cli query tip --testnet-magic 2

Salida esperada:

{
  "block": 10456789,
  "epoch": 490,
  "era": "Conway",
  "hash": "abc123...",
  "slot": 123456789,
  "slotInEpoch": 312000,
  "slotsToEpochEnd": 120000,
  "syncProgress": "99.81"
}

ℹ️ Info: El campo syncProgress debe ir aumentando hacia 100.00. La sincronización inicial puede tardar entre 12 y 48 horas dependiendo del hardware y la conexión.

Variables y alias permanentes

cat >> ~/.bashrc << 'EOF'

# Cardano Node - funciones por red
cn-mainnet() { export CARDANO_NODE_SOCKET_PATH="${HOME}/cardano-my-node/mainnet/socket/node.socket"; }
cn-preprod()  { export CARDANO_NODE_SOCKET_PATH="${HOME}/cardano-my-node/preprod/socket/node.socket"; }
cn-preview()  { export CARDANO_NODE_SOCKET_PATH="${HOME}/cardano-my-node/preview/socket/node.socket"; }

# Alias de consulta
alias cn-tip-mainnet='cn-mainnet && cardano-cli query tip --mainnet'
alias cn-tip-preprod='cn-preprod && cardano-cli query tip --testnet-magic 1'
alias cn-tip-preview='cn-preview && cardano-cli query tip --testnet-magic 2'

# Alias de logs
alias cn-log-mainnet='journalctl -fu cardano-node-mainnet'
alias cn-log-preprod='journalctl -fu cardano-node-preprod'
alias cn-log-preview='journalctl -fu cardano-node-preview'
EOF

source ~/.bashrc

14. Monitoreo con gLiveView

gLiveView es la herramienta de monitoreo en terminal más usada por los stake pool operators. Forma parte del proyecto Guild Operators y muestra en tiempo real el estado del nodo, peers, sincronización, CPU y memoria.

Instalar gLiveView

mkdir -p ~/guild-operators/scripts
cd ~/guild-operators/scripts

curl -s -o gLiveView.sh https://raw.githubusercontent.com/cardano-community/guild-operators/master/scripts/cnode-helper-scripts/gLiveView.sh
curl -s -o env https://raw.githubusercontent.com/cardano-community/guild-operators/master/scripts/cnode-helper-scripts/env

chmod +x gLiveView.sh

Configurar el archivo env

nano ~/guild-operators/scripts/env

Ajusta estas variables según la red:

# Para Mainnet
CNODE_HOME="${HOME}/cardano-my-node/mainnet"
CNODE_PORT=3001
CARDANO_NODE_SOCKET_PATH="${HOME}/cardano-my-node/mainnet/socket/node.socket"
CONFIG="${HOME}/cardano-my-node/mainnet/config/config.json"
TOPOLOGY="${HOME}/cardano-my-node/mainnet/config/topology.json"
LOG_DIR="${HOME}/cardano-my-node/mainnet/logs"
DB_DIR="${HOME}/cardano-my-node/mainnet/db"
# Para Preprod
CNODE_HOME="${HOME}/cardano-my-node/preprod"
CNODE_PORT=3002
CARDANO_NODE_SOCKET_PATH="${HOME}/cardano-my-node/preprod/socket/node.socket"
CONFIG="${HOME}/cardano-my-node/preprod/config/config.json"
TOPOLOGY="${HOME}/cardano-my-node/preprod/config/topology.json"
LOG_DIR="${HOME}/cardano-my-node/preprod/logs"
DB_DIR="${HOME}/cardano-my-node/preprod/db"
# Para Preview
CNODE_HOME="${HOME}/cardano-my-node/preview"
CNODE_PORT=3003
CARDANO_NODE_SOCKET_PATH="${HOME}/cardano-my-node/preview/socket/node.socket"
CONFIG="${HOME}/cardano-my-node/preview/config/config.json"
TOPOLOGY="${HOME}/cardano-my-node/preview/config/topology.json"
LOG_DIR="${HOME}/cardano-my-node/preview/logs"
DB_DIR="${HOME}/cardano-my-node/preview/db"

Ejecutar gLiveView

cd ~/guild-operators/scripts
./gLiveView.sh

Presiona q para salir.

ℹ️ Info: Si usas varias redes, crea una copia del archivo env por red (env-mainnet, env-preprod) y pásala como argumento: ./gLiveView.sh -n preprod.


15. Actualización del nodo

Compilar y actualizar a una nueva versión

# Detener los nodos
sudo systemctl stop cardano-node-mainnet
sudo systemctl stop cardano-node-preprod
sudo systemctl stop cardano-node-preview

# Actualizar el repositorio
cd ~/git/cardano-node
git fetch --all --recurse-submodules --tags

# Cambiar al nuevo tag
git checkout tags/10.6.2

# Recompilar
cabal update
cabal build all 2>&1 | tee build.log

# Copiar los nuevos binarios
sudo cp -p "$(./scripts/bin-path.sh cardano-node)" /usr/local/bin/cardano-node
sudo cp -p "$(./scripts/bin-path.sh cardano-cli)" /usr/local/bin/cardano-cli

# Verificar nueva versión
cardano-node --version

# Reiniciar los servicios
sudo systemctl start cardano-node-mainnet
sudo systemctl start cardano-node-preprod
sudo systemctl start cardano-node-preview

Rollback a versión anterior

# Detener los nodos
sudo systemctl stop cardano-node-mainnet

# Volver al tag anterior en git
cd ~/git/cardano-node
git checkout tags/10.5.0

# Recompilar e instalar
cabal build all
sudo cp -p "$(./scripts/bin-path.sh cardano-node)" /usr/local/bin/cardano-node
sudo cp -p "$(./scripts/bin-path.sh cardano-cli)" /usr/local/bin/cardano-cli

sudo systemctl start cardano-node-mainnet

16. Recursos adicionales

Recurso URL
Repositorio cardano-node https://github.com/IntersectMBO/cardano-node
Release 10.6.2 https://github.com/IntersectMBO/cardano-my-node/releases/tag/10.6.2
Archivos de configuración (Cardano Book) https://book.world.dev.cardano.org
Documentación técnica https://docs.cardano.org

₳ ¡Bienvenido a la red Cardano! ₳