Blog | Yiolabs.com
Nodo Cardano

Nodo Cardano I: Relay Node en Ubuntu

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 características 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

¿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. La sincronización completa de la blockchain puede tardar entre 12 y 48 horas adicionales — si quieres reducirlo a menos de 20 minutos, consulta la sección Mithril antes de iniciar el nodo por primera vez.

Índice

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

Requisitos del sistema

Mínimos recomendados

Componente Mínimo Recomendado
CPU 4 cores x86_64 8 cores
RAM 8 GB (backend OnDisk) 24 GB (backend InMemory)
Almacenamiento SSD 150 GB SSD 300 GB+
Sistema Operativo Ubuntu 22.04.5 LTS Ubuntu 22.04.5 LTS
Conectividad 10 Mbps 100 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.

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 \
    liblmdb-dev

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

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

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

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 $HOME/.bashrc
source $HOME/.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.12.1.0

Instalar dependencias del sistema

cardano-node requiere tres librerías compiladas desde fuente: libsodium, libsecp256k1 y libblst.

libsodium

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

libsecp256k1

cd $HOME/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 $HOME/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

Verifica que las tres librerías quedaron correctamente instaladas antes de continuar:

# libsodium y libsecp256k1 son dinámicas — aparecen en ldconfig
ldconfig -p | grep -E "sodium|secp256"
# libsodium.so.23 (libc6,x86-64) => /usr/local/lib/libsodium.so.23
# libsecp256k1.so.2 (libc6,x86-64) => /usr/local/lib/libsecp256k1.so.2

# libblst es estática (.a) — ldconfig no la lista, verificar manualmente
ls /usr/local/lib/libblst.a /usr/local/include/blst.h /usr/local/lib/pkgconfig/libblst.pc
# Salida esperada (los tres archivos deben existir):
# /usr/local/lib/libblst.a
# /usr/local/include/blst.h
# /usr/local/lib/pkgconfig/libblst.pc

⚠️ Aviso: Si alguna librería no aparece en la salida, revisa los pasos de compilación e instalación correspondientes antes de continuar. Una librería faltante causará un error en la compilación del nodo (sección 7), después de 40 minutos de espera.

Configurar variables de entorno

Añade las variables de entorno al perfil del usuario:

cat >> $HOME/.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"
EOF

source $HOME/.bashrc

Compilar cardano-node 10.6.2

cd $HOME/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

# Compila todo el proyecto (incluye cardano-cli en la mayoría de los casos)
cabal build all

# Compila cardano-cli explícitamente si no se incluyó en el paso anterior
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.15.0.0 - 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.

Descargar archivos de configuración

Cada red usa los mismos nombres de archivo, por lo que deben ir en directorios separados:

mkdir -p $HOME/cardano-my-node/{mainnet,preview}/{config,db,socket,keys,logs}

La estructura quedará así:

$HOME/cardano-my-node/
├── mainnet/
│   ├── config/
│   ├── db/
│   ├── logs/
│   ├── socket/
│   └── keys/
└── preview/
    ├── config/
    ├── db/
    ├── logs/
    ├── socket/
    └── keys/

Descarga los archivos de configuración:

Preview (red de pruebas)

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 $HOME/cardano-my-node/preview/config
  echo "✓ Descargado: ${file}"
done

Mainnet (producción)

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 $HOME/cardano-my-node/mainnet/config
  echo "✓ Descargado: ${file}"
done
Red Flag Magic ID Puerto Uso
Preview --testnet-magic 2 2 3003 Red de pruebas
Mainnet --mainnet — 3001 Producción, ADA real

⚠️ Aviso: Nunca uses ADA real en testnet.

Configurar y ejecutar el nodo

Crea un script de inicio por red:

Script para Preview

cat > $HOME/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 $HOME/cardano-my-node/preview/start-node.sh

Script para Mainnet

cat > $HOME/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 $HOME/cardano-my-node/mainnet/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.

Configurar servicio systemd

Un servicio systemd permite que el nodo relay se inicie automáticamente cuando el servidor arranca y se reinicie solo si falla. Sin esto, el nodo se detendría cada vez que el servidor se reinicie o se caiga, requiriendo intervención manual para volver a levantarlo.

Servicio Preview

sudo tee /etc/systemd/system/cardano-node-preview.service > /dev/null << 'EOF'
[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

Servicio Mainnet

ℹ️ Info: Crea el archivo del servicio ahora para tenerlo listo, pero no lo habilites ni lo inicies. Se activará cuando migres a mainnet y el nodo esté sincronizado.

sudo tee /etc/systemd/system/cardano-node-mainnet.service > /dev/null << 'EOF'
[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

Habilita e inicia el servicio:

# Preview — iniciar ahora
sudo systemctl daemon-reload
sudo systemctl enable cardano-node-preview
sudo systemctl start cardano-node-preview

# Mainnet — ejecutar solo cuando migres a mainnet
sudo systemctl daemon-reload
sudo systemctl enable cardano-node-mainnet
sudo systemctl start cardano-node-mainnet

Comandos útiles

Si has seguido la guía hasta aquí, los comandos son los mismos para cualquier red — solo cambia el sufijo preview o mainnet según la red que quieras operar.

# Ver estado — muestra si el servicio está activo, cuándo inició y los últimos logs
sudo systemctl status cardano-node-<preview|mainnet>

# Ver logs en tiempo real — útil para detectar errores o confirmar que el nodo está sincronizando
journalctl -fu cardano-node-<preview|mainnet>

# Iniciar / Detener / Reiniciar — control manual del servicio
sudo systemctl start cardano-node-<preview|mainnet>
sudo systemctl stop cardano-node-<preview|mainnet>
sudo systemctl restart cardano-node-<preview|mainnet>

# Recargar configuración — necesario después de editar el archivo .service
sudo systemctl daemon-reload
sudo systemctl restart cardano-node-<preview|mainnet>

Verificación y monitoreo

Consultar estado de sincronización

La sincronización es el proceso por el cual el nodo descarga y valida toda la historia de la blockchain desde el bloque génesis hasta el bloque más reciente. Un nodo que no está sincronizado al 100% no puede participar en la red ni validar transacciones — es como intentar participar en una conversación sin haber escuchado el contexto. El campo syncProgress indica el porcentaje completado; hasta que llegue a 100.00 el nodo no estará listo para operar.

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

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

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

Para simplificar el uso diario, agrega estas funciones y aliases a tu .bashrc:

cat >> $HOME/.bashrc << 'EOF'

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

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

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

# Scripts (mithril-client y otros binarios locales)
export PATH="$HOME/scripts:$PATH"
EOF

source $HOME/.bashrc

¿Qué hace cada comando?

  • preview / mainnet — apunta cardano-cli al socket del nodo correcto. Ejecútalo antes de cualquier comando de consulta.
  • tip-<preview|mainnet> — muestra el bloque, slot y progreso de sincronización del nodo.
  • log-<preview|mainnet> — abre los logs del nodo en tiempo real. Útil para detectar errores o confirmar que está sincronizando.

💡 Tip — Sincronización rápida con Mithril: La sincronización inicial puede tardar entre 12 y 48 horas. Si quieres reducir ese tiempo a menos de 20 minutos, detén el nodo ahora y usa Mithril para descargar un snapshot verificado criptográficamente antes de que el nodo siga sincronizando desde cero.

Sincronización con Mithril

Mithril es el proyecto oficial de IOG para descargar snapshots de la blockchain verificados criptográficamente. Reduce el tiempo de sincronización de horas o días a menos de 20 minutos.

Instalar mithril-client

mkdir -p $HOME/scripts
cd $HOME/scripts
curl --proto '=https' --tlsv1.2 -sSf \
    https://raw.githubusercontent.com/input-output-hk/mithril/refs/heads/main/mithril-install.sh \
    | sh -s -- -c mithril-client -d 2603.1 -p $(pwd)
mithril-client --version

Descargar snapshot — Preview

sudo systemctl stop cardano-node-preview
rm -rf $HOME/cardano-my-node/preview/db/*

export CARDANO_NETWORK=preview
export AGGREGATOR_ENDPOINT=https://aggregator.pre-release-preview.api.mithril.network/aggregator
export GENESIS_VERIFICATION_KEY=$(wget -q -O - https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/pre-release-preview/genesis.vkey)

mithril-client cardano-db download latest --download-dir $HOME/cardano-my-node/preview

sudo systemctl start cardano-node-preview

Descargar snapshot — Mainnet

sudo systemctl stop cardano-node-mainnet
rm -rf $HOME/cardano-my-node/mainnet/db/*

export CARDANO_NETWORK=mainnet
export AGGREGATOR_ENDPOINT=https://aggregator.release-mainnet.api.mithril.network/aggregator
export GENESIS_VERIFICATION_KEY=$(wget -q -O - https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/release-mainnet/genesis.vkey)

mithril-client cardano-db download latest --download-dir $HOME/cardano-my-node/mainnet

sudo systemctl start cardano-node-mainnet

ℹ️ Info: Mithril verifica criptográficamente el snapshot antes de instalarlo. Si la verificación falla, el proceso se detiene automáticamente y la base de datos no se modifica.

⚠️ Aviso: El comando rm -rf db/* elimina la base de datos actual. Asegúrate de detener el servicio antes de ejecutarlo.

Monitoreo con gLiveView

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

Instalar gLiveView por red

mkdir -p $HOME/scripts/{mainnet,preview}

for RED in mainnet preview; do
  curl -s -o $HOME/scripts/${RED}/gLiveView.sh \
    https://raw.githubusercontent.com/cardano-community/guild-operators/master/scripts/cnode-helper-scripts/gLiveView.sh
  curl -s -o $HOME/scripts/${RED}/env \
    https://raw.githubusercontent.com/cardano-community/guild-operators/master/scripts/cnode-helper-scripts/env
  chmod +x $HOME/scripts/${RED}/gLiveView.sh
  echo "✓ Instalado: $HOME/scripts/${RED}/"
done

Configurar el archivo env por red

# Preview
sed -i \
  -e 's|#CNODE_HOME=.*|CNODE_HOME="${HOME}/cardano-my-node/preview"|' \
  -e 's|#CNODE_PORT=.*|CNODE_PORT=3003|' \
  -e 's|#CONFIG=.*|CONFIG="${HOME}/cardano-my-node/preview/config/config.json"|' \
  -e 's|#SOCKET=.*|SOCKET="${HOME}/cardano-my-node/preview/socket/node.socket"|' \
  -e 's|#TOPOLOGY=.*|TOPOLOGY="${HOME}/cardano-my-node/preview/config/topology.json"|' \
  -e 's|#LOG_DIR=.*|LOG_DIR="${HOME}/cardano-my-node/preview/logs"|' \
  -e 's|#DB_DIR=.*|DB_DIR="${HOME}/cardano-my-node/preview/db"|' \
  $HOME/scripts/preview/env

# Mainnet
sed -i \
  -e 's|#CNODE_HOME=.*|CNODE_HOME="${HOME}/cardano-my-node/mainnet"|' \
  -e 's|#CNODE_PORT=.*|CNODE_PORT=3001|' \
  -e 's|#CONFIG=.*|CONFIG="${HOME}/cardano-my-node/mainnet/config/config.json"|' \
  -e 's|#SOCKET=.*|SOCKET="${HOME}/cardano-my-node/mainnet/socket/node.socket"|' \
  -e 's|#TOPOLOGY=.*|TOPOLOGY="${HOME}/cardano-my-node/mainnet/config/topology.json"|' \
  -e 's|#LOG_DIR=.*|LOG_DIR="${HOME}/cardano-my-node/mainnet/logs"|' \
  -e 's|#DB_DIR=.*|DB_DIR="${HOME}/cardano-my-node/mainnet/db"|' \
  $HOME/scripts/mainnet/env

Ejecutar gLiveView

# Preview
cd $HOME/scripts/preview && ./gLiveView.sh

# Mainnet
cd $HOME/scripts/mainnet && ./gLiveView.sh

Presiona Esc para salir.

Recursos adicionales

Recurso URL
Repositorio cardano-node https://github.com/IntersectMBO/cardano-node
Release 10.6.2 https://github.com/IntersectMBO/cardano-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
Guild Operators (gLiveView) https://cardano-community.github.io/guild-operators
Mithril https://mithril.network

✅ Resumen

Al completar todos los pasos deberías tener:

  • Un nodo relay de Cardano corriendo en Ubuntu 22.04.5
  • El servicio cardano-node activo y configurado para iniciar automáticamente
  • El nodo sincronizado al 100% con la red seleccionada
  • gLiveView mostrando peers conectados, sincronización y métricas del sistema

El siguiente artículo cubre la configuración del block producer y las claves criptográficas del pool.