🛠️ Mi Experiencia: Instalando Cardano DB-Sync con las Herramientas de Guild Operators

Español Recursos
1

¡Hola a todos! :waving_hand: Como operador de stake pool (o simplemente un entusiasta de Cardano), necesitaba tener acceso rápido y robusto a los datos de la blockchain. Después de un poco de investigación, me decidí por usar Cardano DB-Sync con las increíbles scripts de Guild Operators. ¡Y quiero compartirles mi proceso, paso a paso!

Esta herramienta no solo es potente sino que, gracias a las scripts de Guild, es sorprendentemente ordenada y fácil de mantener. ¡Manos a la obra!

1. Los Tres Pilares (Requisitos Previos)

Antes de empezar, me aseguré de tener mi base lista. Esto es lo que necesitas sí o sí:

  1. Mi Cardano Node (cardano-node) tiene que estar totalmente sincronizado y funcionando. DB-Sync lee directamente de él.
  2. PostgreSQL 17+ instalado. Yo elegí la versión 17 por el rendimiento extra que trae.
  3. El entorno de Guild Operators listo (usuario cnode y variables de entorno).

2. Preparando la Casa de PostgreSQL :house:

La base de datos de Cardano es GIGANTE (¡piensen en cientos de GB!), así que hice una configuración bien dedicada y separada.

A. Creando el Directorio (¡Limpio!)

Para que todo esté ordenado, le di a PostgreSQL su propio espacio, lejos de las carpetas estándar del sistema.

# Asumo que ya estamos en la carpeta del usuario cnode
mkdir -p $HOME/guild-db/pgdb/17
sudo chown -R postgres:postgres $HOME/guild-db

B. Naciendo el Cluster

Con la carpeta lista, inicialicé el cluster. Esto crea todos los archivos de configuración iniciales (postgresql.conf, etc.).

sudo -u postgres /usr/lib/postgresql/17/bin/initdb -D $HOME/guild-db/pgdb/17

C. El Usuario y la Base de Datos

Necesitamos una cuenta especial para DB-Sync. ¡Recuerden poner una contraseña muy fuerte!

# Primero, encendemos temporalmente el servidor para poder hablar con él:
sudo -u postgres /usr/lib/postgresql/17/bin/pg_ctl -D $HOME/guild-db/pgdb/17 start

# 1. ¡Creamos la base de datos!
sudo -u postgres psql -c "CREATE DATABASE cardano_db ENCODING 'UTF8';"

# 2. Creamos la cuenta de DB-Sync. ¡Cambia 'Tu_Contraseña_Secreta'!
sudo -u postgres psql -c "CREATE USER cardano_db_sync WITH PASSWORD 'Tu_Contraseña_Secreta';"

# 3. Le damos privilegios altos (SUPERUSER) para que pueda manejar las extensiones necesarias.
sudo -u postgres psql -c "ALTER USER cardano_db_sync WITH SUPERUSER;"

# 4. Y apagamos para continuar la configuración:
sudo -u postgres /usr/lib/postgresql/17/bin/pg_ctl -D $HOME/guild-db/pgdb/17 stop

3. Instalación Mágica de DB-Sync :sparkles:

Aquí es donde las scripts de Guild Operators hacen la vida fácil. Usé setup-dbsync.sh para encargarse de descargar el código fuente y compilarlo.

A. El Script Hace el Trabajo Pesado

Asegúrate de tener tu variable $PG_VERSION establecida (yo usé export PG_VERSION=17).

# Voy a mi carpeta de Git
cd $HOME/git
wget https://raw.githubusercontent.com/cardano-community/guild-operators/master/scripts/setup-dbsync.sh

# ¡A compilar! Esto toma un buen rato, a ser pacientes.
bash setup-dbsync.sh

B. Conectando los Puntos (Variables de Entorno)

El script crea un archivo de entorno que es la “llave” de conexión. Tuve que editarlo para asegurarme de que supiera dónde está mi base de datos y cuál es la contraseña.

nano $HOME/cnode/db/dbsync.env

Verifiquen que estos valores sean correctos:

Variable Mi Valor
DB_USER cardano_db_sync
DB_PASS Tu_Contraseña_Secreta (¡La que pusiste antes!)
PG_DATADIR $HOME/guild-db/pgdb/$PG_VERSION (La ruta que creamos)

4. Encendiendo los Motores con Systemd :rocket:

Usar systemd es fundamental para que el servidor reinicie los servicios si se caen o si se reinicia el VPS.

A. PostgreSQL al Ataque

Las scripts de Guild ya me crearon el archivo .service para mi cluster personalizado. Solo tuve que copiarlo y habilitarlo.

sudo cp $HOME/cnode/db/cnode-pg-cluster@.service /etc/systemd/system/
sudo systemctl daemon-reload

# Iniciamos y habilitamos el servicio. ¡Ya está corriendo en el background!
sudo systemctl enable cnode-pg-cluster@$PG_VERSION.service
sudo systemctl start cnode-pg-cluster@$PG_VERSION.service

B. Y Ahora DB-Sync

Mismo proceso para el indexador. Ahora sí, empieza la magia.

sudo cp $HOME/cnode/db/cnode-dbsync.service /etc/systemd/system/
sudo systemctl daemon-reload

# Iniciamos la indexación.
sudo systemctl enable cnode-dbsync.service
sudo systemctl start cnode-dbsync.service

5. Verificación: ¿Está Sincronizando? :thinking:

¡La parte más emocionante!

  1. Revisar los Logs: Esto nos dice si está leyendo bloques. Si ven números de bloques subiendo, ¡vamos bien!

    journalctl -f -u cnode-dbsync     tail -f $HOME/cnode/logs/node0.json

  2. Preguntar a la Base de Datos: Entra al shell de PostgreSQL y pregúntale cuál es el último bloque que indexó.

    psql -d cardano_db -U cardano_db_sync -h 127.0.0.1

# Dentro de psql:
SELECT max(block.block_no) FROM block;
\q # Para salir

    Si ese número está cerca del bloque actual de Cardano, ¡Lo lograste! :tada:

La sincronización inicial es larga (piensen en varios días), ¡pero el resultado vale la pena! Ahora tengo un acceso completo y potente a todos los datos de la blockchain.

:construction: Dificultades Encontradas y Soluciones Implementadas (Versión Pública y Segura)

El objetivo central de este proyecto fue habilitar el acceso seguro para un tercero a nuestra base de datos PostgreSQL de Cardano, manteniendo la integridad y el funcionamiento del servicio local DB-Sync.

Este proceso de aseguramiento implicó abordar varias capas de configuración, desde el servicio de base de datos hasta el firewall del sistema operativo. Además, nos encontramos con un desafío de rendimiento al iniciar la sincronización.

1. Dificultad Adicional: El Snapshot y la Memoria :brain:

Dificultad Descripción del Problema Solución Implementada
Uso Excesivo de Memoria al Iniciar Al intentar usar el snapshot pre-indexado que ofrece la comunidad para acelerar la sincronización inicial, el servidor experimentó un consumo de memoria (RAM) desmedido, causando swapping o incluso crashes. Esto sugirió un desajuste en la configuración de la memoria de PostgreSQL (o del sistema operativo) para manejar la restauración de archivos tan grandes. Estrategia de Sincronización Lenta (Desde Cero): La solución más estable fue descartar el uso del snapshot y optar por el método más lento y seguro: sincronizar la blockchain desde el Bloque 0. Aunque esto requiere varios días, garantiza que el proceso sea manejado de forma incremental y estable por el servicio DB-Sync, respetando los límites de memoria del servidor.

2. Configuración de Acceso y Seguridad

Para evitar el uso de nombres predecibles, utilizamos el nombre de base de datos indice_cardano y el usuario data_analyst.

Dificultad Descripción del Problema Solución Implementada
Conectividad Externa Denegada PostgreSQL por defecto escucha solo en 127.0.0.1 (localhost), bloqueando cualquier conexión desde fuera del servidor. Modificación de postgresql.conf: Se cambió el parámetro clave listen_addresses a '*' (o '0.0.0.0'). Este ajuste permite que PostgreSQL escuche en todas las interfaces de red, habilitando la posibilidad de conexiones externas.
Restricción de Autenticación Es necesario que PostgreSQL acepte la conexión remota del colaborador y que la autenticación sea segura. Ajuste de pg_hba.conf: Se añadió una regla para el tercero, usando el nuevo nombre de base de datos y usuario. Se exige la autenticación por contraseña cifrada (md5) para garantizar la seguridad: host indice_cardano data_analyst IP_DEL_TERCERO/32 md5.
Bloqueo por Firewall (UFW) El firewall del sistema operativo (UFW) actúa como la primera barrera, bloqueando el puerto 5432 por defecto. Configuración Fina de UFW: Aplicamos el principio de “mínimo privilegio” con la regla sudo ufw allow from IP_DEL_TERCERO to any port 5432. Esto asegura que solo la IP autorizada tenga acceso directo al servicio de PostgreSQL.

3. Permisos y Gestión del Servicio

Dificultad Descripción del Problema Solución Implementada
Permisos de Usuario El usuario utilizado para la indexación (y el acceso de terceros) requiere amplios privilegios para crear la estructura de la base de datos y manejar extensiones. Asignación de SUPERUSER: Se otorgó al usuario data_analyst el rol de SUPERUSER (ALTER USER data_analyst WITH SUPERUSER;). Esto resolvió errores de permisos, permitiendo que DB-Sync interactúe con el hardware de la base de datos sin restricciones internas.
Gestión del Servicio Personalizado Al usar las scripts de Guild Operators, la ruta de la base de datos (/opt/...) difiere de la ruta estándar de Linux (/var/lib/...), lo que complica la gestión estándar del servicio systemd. Rutas Explícitas y Verificación: Se utilizaron los binarios y rutas de datos explícitos (ej., /usr/lib/postgresql/17/bin/pg_ctl -D /opt/...) para controlar el servicio. La verificación final con herramientas de red confirmó que PostgreSQL estaba escuchando correctamente en TU_IP_PÚBLICA en el puerto 5432.

:white_check_mark: Conclusión

El éxito de este proyecto radicó en aplicar una estrategia de seguridad en capas junto con el aprendizaje empírico sobre el rendimiento. Optamos por la estabilidad (sincronización lenta desde cero) y garantizamos la seguridad del acceso con nombres de base de datos ofuscados y reglas de firewall estrictas.