Sign in Subscribe
Decentraland

How To Deploy A Decentraland Node

Vivian Nguyen

Vivian Nguyen

— 5 min read
How To Deploy A Decentraland Node
How to Deploy a Node on Decentraland

Do you want to join Decentraland? Whether you're a fan or a developer, knowing how to deploy a Decentraland node is crucial to fully engage with the platform. Our article will show you how to set up your own Decentraland node, so you can contribute to the network and be part of the metaverse's governance.

What is a Decentraland Node?

A node in the Decentraland network is commonly known as a Catalyst node. Catalyst nodes provide multiple services, including content, lambda, archipelago, backend for frontend, and additional services. You can find out every detail about the Catalyst node via Decentraland Documentation.

Run a Node on Decentraland
Run a Node on Decentraland

Decentraland Node Requirements

To run a Catalyst node effectively, certain hardware and software requirements must be met:

Hardware Requirements:

  • For public use, the Decentraland Foundation servers use Amazon AWS t2.xlarge instances. However, individual nodes may require smaller specs depending on their intended use.
  • AWS EC2 t2.xlarge specs include 4 vCPUs and 16 GB RAM.
  • Storage capacity of at least 2 TB SSD/HDD is recommended, considering the foundation servers use a little over 1 TB for all storage.

Software Prerequisites:

  • Linux or MacOS operating system.
  • Docker and docker-compose for containerization and deployment.
  • Git for version control.
  • LiveKit Cluster to orchestrate communications between players.

Before setting up a node, consider the following options:

  1. Determine if the node should be publicly exposed on the internet, requiring an internet-exposed instance and a public URL for connection.
  2. Assess the node's purpose, whether for scene and wearable development (smaller hardware specs) or for broader public use (larger specs).
  3. Decide on the entity types to be synced; profiles may be skipped to save time, bandwidth, and disk space during development.

For LiveKit support, two options are available: use a LiveKit Cloud account with a free tier for up to 100 users or set up a self-provisioned LiveKit cluster. The Cloud account is recommended for its ease of setup and scaling management.

How To Deploy A Decentraland Node

Step 1: Clone the Catalyst Owner Repository

Open your terminal and run the following command to clone the Catalyst Owner repository from GitHub:

> git clone https://github.com/decentraland/catalyst-owner.git
Cloning into 'catalyst-owner'...
remote: Enumerating objects: 2392, done.
remote: Counting objects: 100% (602/602), done.
remote: Compressing objects: 100% (168/168), done.
remote: Total 2392 (delta 506), reused 481 (delta 430), pack-reused 1790
Receiving objects: 100% (2392/2392), 926.05 KiB | 1.09 MiB/s, done.
Resolving deltas: 100% (1257/1257), done.
> cd catalyst-owner

Step 2: Configure Environment Variables

Copy the provided example environment files:

# On the /catalyst-owner folder
> cp .env.example .env
> cp .env-advanced.example .env-advanced

Use your preferred text editor to modify these files according to your needs. For instance, set the EMAIL environment variable to a valid email address to receive updates about Certbot certificate expiration. Configure CATALYST_URL to the appropriate URL; for local use, the default http://localhost works.

  • Comms Service

When the LiveKit cluster is accessible, set LiveKit-specific variables for the Comms service, such as LIVEKIT_HOST, LIVEKIT_API_KEY, LIVEKIT_API_SECRET, and ROOM_PREFIX.

LIVEKIT_HOST=wss://livekit-1.mydomain.org
LIVEKIT_API_KEY=API-JjHuvM
LIVEKIT_API_SECRET=J7YSHmNzkNCEfT2
ROOM_PREFIX=my-prefix
  • Content Server

Set CONTENT_SERVER_STORAGE to the desired local storage folder. You can create it by running:

# On the /catalyst-owner folder or wherever CONTENT_SERVER_STORAGE is pointing to
> mkdir storage

Configure SYNC_IGNORED_ENTITY_TYPES if you want to exclude specific entity types during synchronization, such as for development purposes.

Step 3: Launch the Catalyst node

Once your environment variables are configured, it's time to start the node. Run the following command in the root directory of the cloned repository:

# On the /catalyst-owner folder

> ./init.sh
## Loading env variables... [ OK ]
[ OK ]
## Checking if email is configured... [ OK ]
## Checking if storage is configured... [ OK ]
## Checking if catalyst url is configured... [ OK ]
 WARNING: You are not running latest image of Catalyst's Content and Catalyst's Lambdas Nodes.
 WARNING: You are not running latest image of Catalyst's Archipelago Node.
 WARNING: You are not running latest image of Catalyst's Explorer BFF Node.
 - DOCKER_TAG:               45a5154f11b53d55aadfdf7f958e2fce6a964824
 - LIGHTHOUSE_DOCKER_TAG:    latest
 - CATALYST_URL:             http://localhost
 - CONTENT_SERVER_STORAGE:   ./storage
 - EMAIL:                    [email protected]
 - ETH_NETWORK:              mainnet
 - REGENERATE:               0

Starting in 5 seconds...
45a5154f11b53d55aadfdf7f958e2fce6a964824: Pulling from decentraland/catalyst-content
Digest: sha256:d6c2981c57cb9367fdb3228d15b07e4d26e62c902944115937de24ecd3ab6aac
Status: Image is up to date for decentraland/catalyst-content:45a5154f11b53d55aadfdf7f958e2fce6a964824
docker.io/decentraland/catalyst-content:45a5154f11b53d55aadfdf7f958e2fce6a964824
45a5154f11b53d55aadfdf7f958e2fce6a964824: Pulling from decentraland/catalyst-lambdas
Digest: sha256:5605812dd29316afc32e561d2a2ce1311f164f07ef3cd99a1cd60727518636e5
Status: Image is up to date for decentraland/catalyst-lambdas:45a5154f11b53d55aadfdf7f958e2fce6a964824
docker.io/decentraland/catalyst-lambdas:45a5154f11b53d55aadfdf7f958e2fce6a964824
latest: Pulling from decentraland/catalyst-lighthouse
Digest: sha256:fedc10b714823909f0a1c17955eed2f22a02e4f784090848d3253ef734e410d4
Status: Image is up to date for decentraland/catalyst-lighthouse:latest
docker.io/decentraland/catalyst-lighthouse:latest
latest: Pulling from decentraland/archipelago-service
Digest: sha256:e2c1d6fa96a5cfbbf6fb37e3840c0724fb5abeef8c366025a28fab3ad33d6480
Status: Image is up to date for quay.io/decentraland/archipelago-service:latest
quay.io/decentraland/archipelago-service:latest
latest: Pulling from decentraland/explorer-bff
Digest: sha256:fa9e305c44972a8613b01f4cd573d6fb84b0fb03ce953a506fbb06053202913c
Status: Image is up to date for quay.io/decentraland/explorer-bff:latest
quay.io/decentraland/explorer-bff:latest
Stopping nginx ... done
## Using HTTP because CATALYST_URL is set to http://localhost
## Replacing value $katalyst_host on nginx server file... [ OK ]
## Restarting containers...
Creating network "catalyst-owner_default" with the default driver
Creating catalyst-owner_comms-server_1 ... done
Creating node-exporter                   ... done
Creating catalyst-owner_lambdas_1      ... done
Creating postgres                      ... done
Creating catalyst-owner_certbot_1        ... done
Creating nats                            ... done
Creating postgres-exporter               ... done
Creating catalyst-owner_content-server_1 ... done
Creating catalyst-owner_archipelago_1    ... done
Creating catalyst-owner_explorer-bff_1   ... done
Creating nats-exporter                   ... done
Creating cadvisor                        ... done
Creating nginx                           ... done
## Catalyst server is up and running at http://localhost

The initialization script will load environment variables, check configurations, and start the node's containers. Review the output and verify that the Catalyst server is up and running at the designated URL, typically http://localhost.

To monitor the content server's logs, use the following Docker command:

> docker logs catalyst-owner_content-server_1

The synchronization process is essential for your node to offer the same experience as other DAO servers. Synchronization can take several hours. You can check the synchronization status by accessing the content status endpoint, such as http://localhost/content/status.

{
  "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"
}

While synchronizationState is 'Bootstrapping,' the node is operational for deploying new content but isn't up-to-date with other nodes. Once it changes to 'Syncing,' the node is fully synchronized and actively receiving updates.

{
  "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"
}

You can look through the list of environment variables here.

If you intend to contribute to the network's scalability and run your server, you must request approval from the DAO to join the network. You can also inquire about receiving a MANA grant to cover infrastructure expenses.

Ensure your server's hardware specifications align with the suggested requirements mentioned in the hardware section.

Read more