Skip to content

Running a Metagraph Validator Node

Jump to bottom
Marcus Vinicius Girolneto Sousa edited this page Jul 18, 2025 · 5 revisions

🔧 System Requirements

To run a Metagraph Validator Node, ensure your machine meets the following minimum requirements:

  • Memory (RAM):
    • ✅ Minimum: 8 GB
    • 💡 Recommended: 16 GB or more for optimal performance
  • Storage:
    • 💾 At least 1000 GiB (≈1 TB) of SSD storage
  • CPU:
    • ✅ Minimum: 2 vCPU
    • 💡 Recommended: 4 vCPU

These requirements apply whether you’re running on a local machine or a cloud instance.

⚙️ Dependencies

This node runs inside a Docker container, so you’ll need the following installed on your local machine or cloud instance:

Docker Engine

Ensure Docker is installed and running. Installation instructions can be found in the official documentation:

👉 Docker Engine Install Guide

Docker Compose

Docker Compose is required to manage multi-container setups. You can install it by following this guide:

👉 Docker Compose Install Guide

We also need git

Git

👉 Git Install Guide

Make sure git, docker, and docker-compose commands are available in your terminal after installation.

🚀 Installation

To install and run a metagraph validator node, follow the steps below:

1. Clone the Repository

Clone the validator node Docker repository into your machine:

git clone https://github.com/Constellation-Labs/validator-node-docker.git
cd validator-node-docker

2. Prepare Required Files

📂 P12 Files Place your .p12 keystore file (granted access to run on the metagraph) into the corresponding shared-data/:layer directory.

There are three layers:

  • metagraph-l0
  • currency-l1
  • data-l1

Only place the .p12 file in the directories for which your node is authorized according to the metagraph seedlist.

3. Configure Docker Compose

By default, the setup uses the latest image of the PacaSwap metagraph.

✅ If you’re running a PacaSwap node, no image changes are necessary.

If you’re using a different metagraph, update the image tag in the docker-compose.yml accordingly.

4. Create Your .env File

Option 1: Quick Setup (Recommended)

Run the interactive setup wizard to configure your environment:

chmod +x setup.sh
./setup.sh

The setup wizard will guide you through:

  • Environment selection (testnet/integrationnet/mainnet)
  • Network configuration (IP addresses, ports)
  • Credential setup (peer IDs, keystore configuration)
  • Optional features (seedlist, allowance list)
  • Automatic .env file generation

Option 2: Manual Configuration

If you prefer manual setup, create a .env file in the root directory with necessary ports, credentials, node info, and optional seedlist settings:

NODE_IP=0.0.0.0
ENVIRONMENT=testnet

# Example port config
METAGRAPH_L0_PUBLIC_PORT=9100
CURRENCY_L1_PUBLIC_PORT=9200
DATA_L1_PUBLIC_PORT=9300

# Optional seedlist
METAGRAPH_L0_SEEDLIST_URL=https://example.com/seedlist.txt
METAGRAPH_L0_SEEDLIST_NAME=seedlist.txt

# Optional allowance list
METAGRAPH_L0_ALLOWANCE_LIST_URL=https://example.com/allowance_list.txt
METAGRAPH_L0_ALLOWANCE_LIST_NAME=allowance_list.txt

# Peer IDs, keystore config, etc.
...

▶️ Starting the Service

Once you’ve configured everything, starting your validator node is simple using Docker Compose.

🔧 Run the Node (Detached with Logs)

You can use the following single command to:

  1. 🧹 Stop any existing containers
  2. 🔄 Pull the latest image
  3. 🚀 Start the container in detached mode
  4. 📜 Tail the logs immediately
docker-compose down && docker-compose pull && docker-compose up -d && docker-compose logs -f

This command ensures your node is running the latest version and provides real-time logs after startup.

If everything is set up correctly, you should see your node joining the network and transitioning to the Ready state in the logs.

📁 .env Examples

Below is a reference to example .env configurations for available metagraph node operators:

Clone this wiki locally