How to Run a Catalyst Node
¿Alguna vez has sentido curiosidad sobre cómo funcionan los nodos Catalyst de Decentraland? ¿Alguna vez has querido ejecutar tu propio nodo y te sentiste abrumado sobre por dónde empezar? ¿Estás construyendo contenido para Decentraland y te resulta difícil hacer todo el ciclo de desarrollo y pruebas en servidores de producción?
Si estás (o has estado allí), no temas más. Este tutorial te ayudará en el proceso de planificación, averiguar qué necesitas decidir y luego guiarte paso a paso para iniciar el servidor. Además, en caso de que algo no salga según el plan, hay una sección de solución de problemas al final con algunos de los problemas más comunes y cómo solucionarlos.
¿Listo? Manos a la obra.
Hardware requirements
Los servidores de Decentraland Foundation están desplegados en Amazon AWS en instancias t2.xlarge. Entonces, mientras que esos servidores están destinados para uso público, el tuyo puede estar bien con especificaciones mucho más pequeñas, dependiendo de cuál será el uso previsto.
Un AWS EC2 t2.xlarge tiene el siguiente hardware:
4 vCPUs.
16 Gb RAM
Y para almacenamiento de archivos + almacenamiento de DB, un SSD / HDD con capacidad de 2 Tb debería ser más que suficiente. Al momento de escribir esto, los servidores de la foundation están usando un poco más de 1 Tb para todo el almacenamiento.
Software pre-requisites
Los siguientes son requeridos para ejecutar catalyst-owner:
Sistema operativo Linux / MacOS
Docker / docker-compose
Git
LiveKit Cluster
Some options to consider before we start
¿Quieres que tu nodo esté expuesto públicamente en Internet? Si es así, necesitarás una instancia expuesta a internet y una URL pública para conectarte a ella.
¿El nodo se usará para el desarrollo de escenas, wearables, etc? En este caso, las especificaciones de hardware pueden ser mucho menores, ya que probablemente serán una o dos personas accediendo, no cientos de usuarios.
¿Quieres sincronizar todos los tipos de entidad? Si estás usando esto para desarrollar escenas, probablemente quieras omitir la sincronización de perfiles, ya que toman mucho tiempo, ancho de banda y lo más importante espacio en disco y no te beneficiarán para tu objetivo.
LiveKit
El servicio Comms del Catalyst necesita un cluster externo de LiveKit para orquestar las comunicaciones entre jugadores. Para eso, hay dos opciones: usar una cuenta de LiveKit Cloud o ejecutar tu propio cluster de LiveKit.
La recomendación es configurar una cuenta de Livekit Cloud que viene con un tier gratuito que puede gestionar 100 usuarios, o pagar el servicio según el tráfico. Este enfoque es más fácil ya que no requiere provisionar infraestructura extra y el servicio puede gestionar el escalado. De lo contrario, se necesitará provisionar un cluster de LiveKit. LiveKit hace un muy buen trabajo con su documentación:
En caso de que quieras profundizar en los detalles técnicos necesarios para soportar comunicaciones basadas en transporte LiveKit, consulta el ADR-70 New Communications Architecture.
Step by step guide
Lo primero que hay que hacer es clonar el repositorio catalyst-owner desde GitHub
Una vez hecho esto, es momento de configurar las variables de entorno para el nodo, y hacer cualquier cambio apropiado.
Ahora usando tu editor de texto favorito, haz cualquier cambio necesario en estos archivos. Por ejemplo, configurar la variable de entorno EMAIL con un email válido es requerido para que puedas recibir actualizaciones sobre la expiración del certificado de Certbot.
También configurar tu valor particular para CATALYST_URL puede ser requerido, especialmente si tu servidor va a estar expuesto públicamente en Internet. Para uso en tu máquina local, el valor predeterminado de http://localhost funcionará.
Comms Service
Una vez que el cluster de LiveKit esté disponible, necesitarás establecer las variables específicas de LiveKit para que el servicio Comms funcione, por ejemplo:
La variable ROOM_PREFIX es opcional y puede configurarse para identificar salas de LiveKit creadas por el Catalyst. Esto es útil si más de un Catalyst está usando el mismo Cluster de LiveKit.
Content Server
Hay una variable llamada CONTENT_SERVER_STORAGE que define la carpeta local que el servidor de contenido usará para almacenamiento. Esto por defecto es CONTENT_SERVER_STORAGE=./storage. Puedes cambiar este valor para almacenar archivos en otro lugar, o al menos asegurarte de que la carpeta referenciada existe. Puede que necesites crearla así:
Hay otra variable interesante SYNC_IGNORED_ENTITY_TYPES que permite ignorar ciertos tipos de entidad durante el proceso de sincronización. Si vas a usar el servidor Catalyst para desarrollo, quizás no necesites que se sincronice todo tipo de contenido. Puedes establecer la variable de entorno SYNC_IGNORED_ENTITY_TYPES="profile,store" para que solo las escenas y wearables se traigan de los servidores del DAO. Esto ahorrará mucho tiempo, ancho de banda y almacenamiento en disco en tu servidor.
💡 Para una lista más exhaustiva de variables de entorno soportadas, por favor echa un vistazo a la sección Environment variables abajo.
Launch the Catalyst node
Una vez que todas las variables de entorno han sido configuradas, es momento de iniciar el nodo. Eso debería ser tan fácil como ejecutar el script init.sh en la carpeta raíz.
Si todo salió bien, ahora tenemos un nodo completo de Decentraland ejecutándose. Ahora puedes ir al navegador y escribir la URL. Si usas el predeterminado, debería ser http://localhost.
Podemos verificar los logs del servidor de contenido con este comando docker:
Aunque el servidor ahora está ejecutándose, no está 100% listo para estar en funcionamiento. Necesita sincronizar el contenido de los otros servidores del DAO para que pueda ofrecer la misma experiencia a usuarios conectados a él. La sincronización puede tomar mucho tiempo. En una buena conexión a internet, 6 horas debería ser bastante común. Así que... tiempo de tomar un café, una siesta, un buen descanso nocturno, y volver mañana.
Una forma de saber si la sincronización está completa consiste en verificar los resultados del endpoint de estado de contenido: http://localhost/content/status (usa tu URL aquí).
Mientras synchronizationState sea Bootstrapping, el nodo suspenderá temporalmente la aceptación de nuevos deployments. Esta medida asegura que no se desplieguen nuevas entidades hasta que el nodo esté actualizado dentro de la red del DAO. Una vez que el estado cambie a Syncing, indica que el nodo se ha puesto al día exitosamente y ahora está recibiendo continuamente las últimas actualizaciones. Este es el estado saludable en el que el nodo está completamente funcionando y aceptando nuevos deployments.
Si eres más del tipo cli, puedes hacer grep en los logs de la imagen docker del servidor de contenido para este mensaje: Starting to sync entities from servers pointer changes. Una vez que veas ese texto, el servidor de contenido está completamente sincronizado y listo para uso completo.
Environment variables
La siguiente es una lista completa de todas las variables de entorno del servidor de contenido con sus valores predeterminados, como se registra en los logs del servidor de contenido durante el inicio:
Using your node for production
Si quieres ejecutar tu propio servidor y ayudar a escalar la red, primero que todo eso es increíble, la comunidad y la foundation realmente aprecian que lo hagas.
En este caso, tendrás que pasar por el proceso de solicitar aprobación al DAO para unirte a la red visitando este enlace. También puedes solicitar un grant de MANA para cubrir los gastos de infraestructura y gestión.
Es importante que tus especificaciones de hardware estén más alineadas con lo sugerido arriba en los requisitos de hardware, ya que el servidor será usado por cualquier miembro de la comunidad para entrar a Decentraland.
API Specs
Para más detalles sobre las APIs para servidores de content, lambdas y comms puedes consultar las API specs.
Troubleshooting/FAQ
Algunas cosas podrían salir mal al iniciar tu servidor. Aquí hay algunos de los problemas más comunes encontrados con el tiempo y cómo solucionarlos.
Port 5432 is used by local postgres
Si ejecutas el nodo en una máquina usada para desarrollo, o si ya está alojando otros servicios, es probable que ya haya un servidor de base de datos postgres ejecutándose en esa máquina. Así que el puerto 5432 ya estará tomado.
La forma más fácil de solucionar esto es detener el postgres que ya está ejecutándose localmente y luego reiniciar el contenedor docker de postgres usando docker start postgres.
Si tienes conocimiento de docker compose, puedes empezar a jugar con docker-compose.yml y variables de entorno para intentar que funcione en un puerto diferente. Por el bien de mantener las cosas simples aquí, evitaremos ir por ese camino en este tutorial.
Port 80 port is used by local nginx
Lo mismo puede suceder con el puerto 80 (e incluso el puerto 443). Si estás ejecutando nginx en la máquina local, es probable que los puertos 80/443 ya estén vinculados a ese servicio, por lo que el contenedor Docker de Catalyst no podrá usarlos.
Nuevamente, el enfoque más simple sería detener el servicio nginx local y luego reiniciar el contenedor docker usando docker start nginx. O alternativamente, necesitas aprovechar docker-compose.yml y .env para que funcione en un puerto diferente.
Additional docs for reference
Si quieres entender mejor qué hace un servidor Catalyst, qué servicios incluye, etc. puedes consultar el repo de arquitectura https://github.com/decentraland/architecture que explica las partes en detalle.
Si te gustaría contribuir al código de servidores Catalyst, asegúrate de revisar la guía de contribución para aprender sobre nuestro proceso de desarrollo, cómo proponer correcciones de errores y mejoras, y cómo construir y probar tus cambios.
Y finalmente, si necesitas contactar al equipo, puedes hacerlo vía Discord o enviando GitHub issues.
Last updated