Running Validator Nodes using Docker

Using Docker is a popular way to run Shardeum validator nodes, offering isolation and easier management. Here’s how to configure your nodes, especially when using Docker Compose.

Understanding Ports

Your Shardeum validator node needs to communicate with the outside world and other nodes. This is done through specific ports:

Internal P2P Port (Default: 9001) — Used for core peer-to-peer communication between validator nodes within the Shardeum network.
External P2P Port (Default: 10001) — Used for other types of network interactions, including some public API queries like /nodeinfo.
Dashboard Port (Default: 8080) — Used to access the local validator dashboard GUI in a web browser.

When running inside a Docker container, these internal container ports need to be mapped to ports on your host machine to be accessible from the internet (for P2P ports) or your local machine (for the dashboard).

Environment Variables for Port Configuration

You set these ports for your validator instance using environment variables:

SHMINT: Sets the internal P2P port inside the container.
SHMEXT: Sets the external P2P port inside the container.
DASHPORT: Sets the dashboard port inside the container.

How the Node Registers Itself

The validator software, upon starting, attempts to discover its public IP address (e.g., by querying external IP lookup services). It then registers itself with the Shardeum network using this discovered public IP and the SHMINT and SHMEXT port numbers you've configured via environment variables. This is how other nodes know how to reach it.

Single Validator Node with Docker Compose

Here’s a basic docker-compose.yml example for a single validator:

version: '3.8'
services:
  shardeum-validator-001:
    image: ghcr.io/shardeum/shardeum-validator:latest # Always check for the latest recommended tag
    container_name: shardeum-validator-001
    restart: always
    environment:
      - PRIV_KEY=<YOUR_VALIDATOR_PRIVATE_KEY_HEX> # Optional: only if you want to pre-set the validator key
      - SHMINT=9001
      - SHMEXT=10001
      - DASHPORT=8080
    ports:
      - "9001:9001"
      - "10001:10001"
      - "8080:8080"
    volumes:
      - /home/user/shardeum/node001/config:/home/node/.shardeum
    cap_add:
      - NET_ADMIN

Explanation

image: Specifies the Docker image to use. Always check the official Shardeum documentation or announcements for the correct and latest image tag.
container_name: A friendly name for your container.
restart: Ensures the container restarts if it stops unexpectedly.
environment:
- PRIV_KEY: Optional; initializes with a private key if set. Otherwise, a new one is generated and stored in secrets.json.
- SHMINT, SHMEXT, DASHPORT: Define the application’s internal ports.
ports:
- Format: "HOST_PORT:CONTAINER_PORT"
- Ensure these ports are open on your server firewall.
volumes:
- Required to persist validator identity (secrets.json) and configuration.
- Ensure the path /home/node/.shardeum is accurate for your image version.
cap_add:
- NET_ADMIN may be required on systems using VPNs or custom networking.

Running Multiple Validator Nodes on the Same Host

version: '3.8'
services:
  shardeum-validator-001:
    image: ghcr.io/shardeum/shardeum-validator:stagenet-v1.19.0
    container_name: shardeum-validator-001
    restart: always
    environment:
      - SHMINT=9001
      - SHMEXT=10001
      - DASHPORT=8080
    ports:
      - "9001:9001"
      - "10001:10001"
      - "8080:8080"
    volumes:
      - /home/user/shardeum/node001/config:/home/node/.shardeum
 
  shardeum-validator-002:
    image: ghcr.io/shardeum/shardeum-validator:stagenet-v1.19.0
    container_name: shardeum-validator-002
    restart: always
    environment:
      - SHMINT=9002
      - SHMEXT=10002
      - DASHPORT=8081
    ports:
      - "9002:9002"
      - "10002:10002"
      - "8081:8081"
    volumes:
      - /home/user/shardeum/node002/config:/home/node/.shardeum
 
  shardeum-validator-003:
    image: ghcr.io/shardeum/shardeum-validator:stagenet-v1.19.0
    container_name: shardeum-validator-003
    restart: always
    environment:
      - SHMINT=9003
      - SHMEXT=10003
      - DASHPORT=8082
    ports:
      - "9003:9003"
      - "10003:10003"
      - "8082:8082"
    volumes:
      - /home/user/shardeum/node003/config:/home/node/.shardeum

Key Changes for Multiple Nodes

Unique Port Numbers: Each instance needs distinct values for SHMINT, SHMEXT, and DASHPORT.
Matching Port Mappings: Ensure that host-to-container port mappings match the defined environment variables.
Unique Volumes: Each validator needs its own config path to avoid identity/data overlap.
Firewall Configuration: Open all required ports (e.g., 9001–9003, 10001–10003).

Checking Port Accessibility

To check if your node is publicly accessible:

curl http://YOUR_SERVER_PUBLIC_IP:HOST_PORT_FOR_SHMEXT/nodeinfo

Example:

curl http://123.45.67.89:10001/nodeinfo

If you receive JSON data, your node is reachable. If not, verify:

Docker port mappings
Server firewall or security group settings
General network connectivity

Updating Validator Images

When a new version is released:

Pull the updated image:

docker pull ghcr.io/shardeum/shardeum-validator:NEW_TAG

Update your docker-compose.yml file with the new tag.
Restart your containers:

docker-compose down
docker-compose up -d

Your validator identity will persist if secrets.json is stored in a mapped volume.

Running Validator Nodes using Docker

On this page