> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/contributor/contributor-pt/tutoriais/getting-started.md). # Introdução 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](https://cloud.livekit.io/) 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: * [Implementação](https://docs.livekit.io/oss/deployment/) * [Configuração distribuída](https://docs.livekit.io/oss/deployment/distributed/) *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*](https://adr.decentraland.org/adr/ADR-70)*.* ### Guia passo a passo A primeira coisa a fazer é clonar o [catalyst-owner](https://github.com/decentraland/catalyst-owner) repositório do GitHub ```bash > git clone https://github.com/decentraland/catalyst-owner.git A clonar para 'catalyst-owner'... remoto: A enumerar objetos: 2392, concluído. remoto: A contar objetos: 100% (602/602), concluído. remoto: A comprimir objetos: 100% (168/168), concluído. remoto: Total 2392 (delta 506), reutilizados 481 (delta 430), pack-reused 1790 A receber objetos: 100% (2392/2392), 926.05 KiB | 1.09 MiB/s, concluído. A resolver deltas: 100% (1257/1257), concluído. > cd catalyst-owner ``` Assim que isso estiver feito, é tempo de configurar as variáveis de ambiente do nó e fazer as alterações necessárias. ```bash # Na pasta /catalyst-owner > cp .env.example .env > cp .env-advanced.example .env-advanced ``` 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: ``` LIVEKIT_HOST=wss://livekit-1.mydomain.org LIVEKIT_API_KEY=API-JjHuvM LIVEKIT_API_SECRET=J7YSHmNzkNCEfT2 ROOM_PREFIX=my-prefix ``` 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: ```bash # Na pasta /catalyst-owner ou onde quer que CONTENT_SERVER_STORAGE esteja a apontar > mkdir storage ``` 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](#environment-variables) 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. ```bash # Na pasta /catalyst-owner > ./init.sh ## A carregar variáveis de ambiente... [ OK ] [ OK ] ## A verificar se o email está configurado... [ OK ] ## A verificar se o armazenamento está configurado... [ OK ] ## A verificar se o URL do catalyst está configurado... [ OK ] AVISO: Não está a executar a imagem mais recente dos nós Content e Lambdas do Catalyst. AVISO: Não está a executar a imagem mais recente do Nó Archipelago do Catalyst. AVISO: Não está a executar a imagem mais recente do Nó Explorer BFF do Catalyst. - DOCKER_TAG: 45a5154f11b53d55aadfdf7f958e2fce6a964824 - LIGHTHOUSE_DOCKER_TAG: latest - CATALYST_URL: http://localhost - CONTENT_SERVER_STORAGE: ./storage - EMAIL: a@a.com - ETH_NETWORK: mainnet - REGENERATE: 0 A iniciar dentro de 5 segundos... 45a5154f11b53d55aadfdf7f958e2fce6a964824: A fazer pull de decentraland/catalyst-content Digest: sha256:d6c2981c57cb9367fdb3228d15b07e4d26e62c902944115937de24ecd3ab6aac Estado: A imagem está atualizada para decentraland/catalyst-content:45a5154f11b53d55aadfdf7f958e2fce6a964824 docker.io/decentraland/catalyst-content:45a5154f11b53d55aadfdf7f958e2fce6a964824 45a5154f11b53d55aadfdf7f958e2fce6a964824: A fazer pull de decentraland/catalyst-lambdas Digest: sha256:5605812dd29316afc32e561d2a2ce1311f164f07ef3cd99a1cd60727518636e5 Estado: A imagem está atualizada para decentraland/catalyst-lambdas:45a5154f11b53d55aadfdf7f958e2fce6a964824 docker.io/decentraland/catalyst-lambdas:45a5154f11b53d55aadfdf7f958e2fce6a964824 latest: A fazer pull de decentraland/catalyst-lighthouse Digest: sha256:fedc10b714823909f0a1c17955eed2f22a02e4f784090848d3253ef734e410d4 Estado: A imagem está atualizada para decentraland/catalyst-lighthouse:latest docker.io/decentraland/catalyst-lighthouse:latest latest: A fazer pull de decentraland/archipelago-service Digest: sha256:e2c1d6fa96a5cfbbf6fb37e3840c0724fb5abeef8c366025a28fab3ad33d6480 Estado: A imagem está atualizada para quay.io/decentraland/archipelago-service:latest quay.io/decentraland/archipelago-service:latest latest: A fazer pull de decentraland/explorer-bff Digest: sha256:fa9e305c44972a8613b01f4cd573d6fb84b0fb03ce953a506fbb06053202913c Estado: A imagem está atualizada para quay.io/decentraland/explorer-bff:latest quay.io/decentraland/explorer-bff:latest A parar nginx ... concluído ## A usar HTTP porque CATALYST_URL está definido para http://localhost ## A substituir o valor $katalyst_host no ficheiro do servidor nginx... [ OK ] ## A reiniciar os contentores... A criar a rede "catalyst-owner_default" com o controlador predefinido A criar catalyst-owner_comms-server_1 ... concluído A criar node-exporter ... concluído A criar catalyst-owner_lambdas_1 ... concluído A criar postgres ... concluído A criar catalyst-owner_certbot_1 ... concluído A criar nats ... concluído A criar postgres-exporter ... concluído A criar catalyst-owner_content-server_1 ... concluído A criar catalyst-owner_archipelago_1 ... concluído A criar catalyst-owner_explorer-bff_1 ... concluído A criar nats-exporter ... concluído A criar cadvisor ... concluído A criar nginx ... concluído ## O servidor Catalyst está a funcionar em http://localhost ``` 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`](http://localhost/). Podemos verificar os logs do content server com este comando docker: ```bash > docker logs catalyst-owner_content-server_1 ``` 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](https://decentraland.github.io/catalyst-monitor) 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: (use aqui o seu URL). ```json { "synchronizationStatus": { "lastSyncWithDAO": 1658153514917, "synchronizationState": "Bootstrapping" }, "snapshot": { "entities": { "profile": 1271331, "scene": 23477, "wearable": 17351, "store": 890 }, "lastUpdatedTime": 1658153414530 }, "version": "v3", "commitHash": "9a2e0d5d05d02646df2e1e5d00436d3166a07aa1", "catalystVersion": "4.8.6", "ethNetwork": "mainnet" } ``` 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. ```json { "synchronizationStatus": { "lastSyncWithDAO": 1658153872301, "synchronizationState": "Syncing" }, "snapshot": { "entities": { "profile": 1271317, "scene": 23477, "store": 890, "wearable": 17350 }, "lastUpdatedTime": 1658152050030 }, "version": "v3", "commitHash": "9a2e0d5d05d02646df2e1e5d00436d3166a07aa1", "catalystVersion": "4.8.6", "ethNetwork": "mainnet" } ``` 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: ```jsx STORAGE_ROOT_FOLDER: "/app/storage/content_server/" DENYLIST_FILE_NAME: "denylist.txt" DENYLIST_URLS: "https://config.decentraland.org/denylist" SYNC_IGNORED_ENTITY_TYPES: "" FOLDER_MIGRATION_MAX_CONCURRENCY: 1000 SERVER_PORT: 6969 LOG_REQUESTS: false UPDATE_FROM_DAO_INTERVAL: 1800000 SYNC_WITH_SERVERS_INTERVAL: 45000 CHECK_SYNC_RANGE: 1200000 DECENTRALAND_ADDRESS: "0x1337e0507eb4ab47e08a179573ed4533d9e22a7b" DEPLOYMENTS_DEFAULT_RATE_LIMIT_TTL: 60 DEPLOYMENTS_DEFAULT_RATE_LIMIT_MAX: 300 ETH_NETWORK: "mainnet" LOG_LEVEL: "debug" FETCH_REQUEST_TIMEOUT: "2m" USE_COMPRESSION_MIDDLEWARE: false BOOTSTRAP_FROM_SCRATCH: false REQUEST_TTL_BACKWARDS: 1200000 LAND_MANAGER_SUBGRAPH_URL: "https://api.thegraph.com/subgraphs/name/decentraland/land-manager" COLLECTIONS_L1_SUBGRAPH_URL: "https://api.thegraph.com/subgraphs/name/decentraland/collections-ethereum-mainnet" COLLECTIONS_L2_SUBGRAPH_URL: "https://api.thegraph.com/subgraphs/name/decentraland/collections-matic-mainnet" THIRD_PARTY_REGISTRY_L2_SUBGRAPH_URL: "https://api.thegraph.com/subgraphs/name/decentraland/tpr-matic-mainnet" BLOCKS_L1_SUBGRAPH_URL: "https://api.thegraph.com/subgraphs/name/decentraland/blocks-ethereum-mainnet" BLOCKS_L2_SUBGRAPH_URL: "https://api.thegraph.com/subgraphs/name/decentraland/blocks-matic-mainnet" PSQL_DATABASE: "content" PSQL_HOST: "postgres" PSQL_SCHEMA: "public" PSQL_PORT: "5432" GARBAGE_COLLECTION: true GARBAGE_COLLECTION_INTERVAL: 21600000 PG_IDLE_TIMEOUT: 30000 PG_QUERY_TIMEOUT: 60000 PG_STREAM_QUERY_TIMEOUT: 600000 SNAPSHOT_FREQUENCY_IN_MILLISECONDS: 21600000 CUSTOM_DAO: undefined DISABLE_SYNCHRONIZATION: false SYNC_STREAM_TIMEOUT: "10m" CONTENT_SERVER_ADDRESS: "http://localhost/content/" REPOSITORY_QUEUE_MAX_CONCURRENCY: 50 REPOSITORY_QUEUE_MAX_QUEUED: 300 REPOSITORY_QUEUE_TIMEOUT: "1m" ENTITIES_CACHE_SIZE: 150000 DEPLOYMENT_RATE_LIMIT_MAX: {} DEPLOYMENT_RATE_LIMIT_TTL: {} VALIDATE_API: false RETRY_FAILED_DEPLOYMENTS_DELAY_TIME: 900000 ``` ### 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](https://governance.decentraland.org/submit/catalyst/). 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](https://decentraland.github.io/catalyst-api-specs). ### 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 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](https://github.com/decentraland/catalyst/blob/main/docs/CONTRIBUTING.md) 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](https://discord.com/channels/417796904760639509/948230185457696820) ou enviando [issues no GitHub](https://github.com/decentraland/catalyst/issues). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.decentraland.org/contributor/contributor-pt/tutoriais/getting-started.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.