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
- Introducción
- Requisitos del sistema
- Preparar Ubuntu 22.04.5
- Hardening de Ubuntu Server 22.04.5
- Crear usuario cardano
- Instalar GHCup, GHC y Cabal
- Instalar dependencias del sistema
- Configurar variables de entorno
- Compilar cardano-node 10.6.2
- Descargar archivos de configuración
- Configurar y ejecutar el nodo
- Configurar servicio systemd
- Verificación y monitoreo
- Monitoreo con gLiveView
- Actualización del nodo
- 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
sudoantes 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
-j1al 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
preprodopreview. 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-nodeya 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
syncProgressdebe ir aumentando hacia100.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
envpor 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! ₳