Como executar um Catalyst Node
Alguma vez sentiu curiosidade sobre como funcionam os nós Catalyst da Decentraland? Alguma vez quis executar o seu próprio nó e sentiu-se sobrecarregado sem saber por onde começar? Está a criar conteúdo para a Decentraland e acha difícil fazer todo o ciclo de desenvolvimento e testes em servidores de produção?
Se é esse o seu caso, não tema mais. Este tutorial irá ajudá-lo no processo de planeamento, a perceber o que precisa decidir e depois guiá-lo passo a passo no arranque do servidor. Além disso, caso algo não corra conforme o planeado, há uma secção de resolução de problemas no final com alguns dos problemas mais comuns e como resolvê-los.
Pronto? Mãos à obra.
Requisitos de hardware
Os servidores da Decentraland Foundation estão implementados na Amazon AWS em t2.xlarge instâncias. Portanto, embora esses servidores se destinem a uso público, o seu próprio pode ficar bem com especificações muito menores, dependendo de qual será a utilização pretendida.
Uma instância AWS EC2 t2.xlarge tem o seguinte hardware:
4 vCPUs.
16 Gb de RAM
E para armazenamento de ficheiros + armazenamento da BD, um SSD / HDD com capacidade de 2 Tb deverá ser mais do que suficiente. No momento em que isto é escrito, os servidores da foundation estão a usar pouco mais de 1 Tb para todo o armazenamento.
Pré-requisitos de software
O seguinte é necessário para executar catalyst-owner:
Sistema operativo Linux / MacOS
Docker / docker-compose
Git
LiveKit Cluster
Algumas opções a considerar antes de começarmos
Quer que o seu nó seja exposto publicamente na Internet? Nesse caso, precisará de uma instância exposta à Internet e de um URL público para se ligar a ela.
O nó vai ser utilizado para o desenvolvimento de scenes, wearables, etc.? Neste caso, as especificações de hardware podem ser muito menores, pois provavelmente será uma ou duas pessoas a aceder-lhe, e não centenas de utilizadores.
Quer sincronizar todos os tipos de entities? Se estiver a usar isto para desenvolver scenes, provavelmente não precisa que todos os tipos de conteúdo sejam sincronizados. Pode definir a variável de ambiente
LiveKit
É necessário um cluster externo do LiveKit para o serviço Comms do Catalyst orquestrar as comunicações entre jogadores. Para isso, há duas opções: usar uma conta do LiveKit Cloud ou executar o seu próprio cluster LiveKit.
A recomendação é configurar uma conta do LiveKit Cloud que inclui um nível gratuito que pode gerir 100 utilizadores, ou pagar o serviço de acordo com o tráfego. Esta abordagem é mais fácil, pois não requer provisionar infraestrutura adicional e o serviço pode gerir a escalabilidade. Caso contrário, será necessário provisionar um cluster LiveKit. A LiveKit faz um excelente trabalho com a sua documentação:
Caso queira aprofundar os detalhes técnicos necessários para suportar comunicações baseadas em transporte LiveKit, consulte o ADR-70 Nova arquitetura de comunicações.
Guia passo a passo
A primeira coisa a fazer é clonar o catalyst-owner repositório do GitHub
Assim que isso estiver feito, é tempo de configurar as variáveis de ambiente do nó e fazer as alterações necessárias.
Agora, usando o seu editor de texto favorito, faça quaisquer alterações necessárias nestes ficheiros. Por exemplo, configurar a EMAIL variável de ambiente com um email válido é necessário para que possa receber atualizações sobre a expiração do certificado Certbot.
Também pode ser necessário definir o valor específico de CATALYST_URL especialmente se o seu servidor vai ser exposto publicamente na Internet. Para utilização na sua máquina local, o valor predefinido http://localhost serve.
Serviço Comms
Assim que o cluster LiveKit estiver disponível, terá de definir as variáveis LiveKit específicas para o serviço Comms funcionar, por exemplo:
O A variável ROOM_PREFIX é opcional e pode ser configurada para identificar as salas LiveKit criadas pelo Catalyst. Isto é útil se mais de um Catalyst estiver a usar o mesmo LiveKit Cluster.
Servidor de conteúdo
Existe uma variável chamada CONTENT_SERVER_STORAGE que define a pasta local que o content server usará para armazenamento. O valor predefinido é CONTENT_SERVER_STORAGE=./storage. Pode alterar este valor para guardar ficheiros noutro local, ou pelo menos certificar-se de que a pasta referenciada existe. Talvez precise de a criar assim:
Existe outra variável interessante SYNC_IGNORED_ENTITY_TYPES que permite ignorar certos tipos de entities durante o processo de sincronização. Se for utilizar o servidor Catalyst para desenvolvimento, talvez não precise que todos os tipos de conteúdo sejam sincronizados. Pode definir a variável de ambiente SYNC_IGNORED_ENTITY_TYPES="profile,store" para que apenas scenes e wearables sejam obtidos dos servidores da DAO. Isto poupará muito tempo, largura de banda e armazenamento em disco no seu servidor.
💡 Para uma lista mais exaustiva das variáveis de ambiente suportadas, consulte a secção Variáveis de ambiente abaixo.
Iniciar o nó Catalyst
Assim que todas as variáveis de ambiente estiverem configuradas, está na hora de iniciar o nó. Isso deve ser tão fácil como executar o script init.sh na pasta raiz.
Se tudo correu bem, agora temos um nó completo da Decentraland em execução. Agora pode ir ao browser e escrever o URL. Se estiver a usar o valor predefinido, deverá ser http://localhost.
Podemos verificar os logs do content server com este comando docker:
Apesar de o servidor já estar em execução, ainda não está 100% pronto para entrar em funcionamento. Precisa de sincronizar o conteúdo dos outros servidores da DAO para que possa oferecer a mesma experiência aos utilizadores ligados a ele. A sincronização pode demorar bastante. Numa boa ligação à Internet, 6 horas deverá ser bastante comum. Portanto... é tempo de tomar um café, uma sesta, uma boa noite de descanso e voltar amanhã.
Uma forma de saber se a sincronização está concluída consiste em verificar os resultados do endpoint de estado do conteúdo: http://localhost/content/status (use aqui o seu URL).
Enquanto synchronizationState é Bootstrapping, o nó irá suspender temporariamente a aceitação de novas implementações. Esta medida garante que não são implementadas novas entities até que o nó fique atualizado dentro da rede DAO. Assim que o estado mudar para Syncing, isso indica que o nó alcançou com sucesso o estado atual e está agora a receber continuamente as últimas atualizações. Este é o estado saudável em que o nó está totalmente funcional e aceita novas implementações.
Se for mais do tipo cli, pode fazer grep aos logs da imagem docker do content server para esta mensagem: A começar a sincronizar entities a partir de alterações dos ponteiros dos servidores. Assim que vir esse texto, o content server está totalmente sincronizado e pronto para uso completo.
secção Variáveis de ambiente
Segue-se uma lista exaustiva de todas as variáveis de ambiente do content server com os seus valores predefinidos, conforme registado nos logs do content server durante o arranque:
Usar o seu nó para produção
Se quiser executar o seu próprio servidor e ajudar a escalar a rede, antes de mais isso é fantástico; a comunidade e a foundation apreciam muito que o faça.
Neste caso, terá de passar pelo processo de solicitar aprovação à DAO para aderir à rede, visitando este link. Também pode pedir uma bolsa MANA para cobrir as despesas de infraestrutura e gestão.
É importante que as especificações do seu hardware estejam mais alinhadas com o que é sugerido acima nos requisitos de hardware, uma vez que o servidor será utilizado por qualquer membro da comunidade para entrar na Decentraland.
Especificações da API
Para mais detalhes sobre as APIs dos servidores de conteúdo, lambdas e comms, pode consultar as especificações da API.
Resolução de problemas/FAQ
Algumas coisas podem correr mal ao iniciar o seu servidor. Aqui ficam alguns dos problemas mais comuns encontrados ao longo do tempo e como resolvê-los.
A porta 5432 é usada pelo postgres local
Se executar o nó numa máquina usada para desenvolvimento, ou se ela já estiver a alojar outros serviços, é provável que já exista um servidor de base de dados postgres a correr nessa máquina. Portanto, a porta 5432 já estará ocupada.
A forma mais fácil de resolver isto é parar o postgres que já está a correr localmente e depois reiniciar o contentor docker do postgres usando docker start postgres.
Se tiver conhecimentos de docker compose, pode começar a mexer em docker-compose.yml e nas variáveis de ambiente para tentar fazê-lo funcionar numa porta diferente. Para simplificar as coisas aqui, evitaremos seguir esse caminho neste tutorial.
A porta 80 é usada pelo nginx local
A mesma coisa pode acontecer com a porta 80 (e até com a 443). Se estiver a executar o nginx na máquina local, é provável que as portas 80/443 já estejam atribuídas a esse serviço, pelo que o contentor Docker do Catalyst não as conseguirá usar.
Mais uma vez, a abordagem mais simples seria parar o serviço nginx local e depois reiniciar o contentor docker usando docker start nginx. Ou, em alternativa, precisa de recorrer a docker-compose.yml e .env para o fazer funcionar numa porta diferente.
Documentação adicional para referência
Se quiser compreender melhor o que um servidor Catalyst faz, que serviços inclui, etc., pode consultar o repositório de arquitetura https://github.com/decentraland/architecture que explica as partes em detalhe.
Se quiser contribuir para o código dos servidores Catalyst, certifique-se de consultar o guia de contribuição para aprender sobre o nosso processo de desenvolvimento, como propor correções de bugs e melhorias, e como construir e testar as suas alterações.
E por fim, se precisar de contactar a equipa, pode fazê-lo via Discord ou enviando issues no GitHub.
Atualizado