Docker Deployment

Overview

SSV Node provides official Docker images for easy deployment. This guide covers deploying SSV Node using Docker and Docker Compose for both single-node and multi-node configurations.

Prerequisites

Before deploying SSV Node with Docker, ensure you have:

Docker Engine (v20.10 or later)
Docker Compose (v2.0 or later)
Access to Ethereum Execution (ETH1) and Consensus (ETH2) nodes
Operator private keys (see Generating Operator Keys)
At least 4GB RAM and 50GB disk space
Ports 12001 (UDP) and 13001 (TCP) available and open

Docker Image

The official SSV Node Docker image is available at:

ssvlabs/ssv-node:latest

You can also use specific version tags:

ssvlabs/ssv-node:v1.x.x

Generating Operator Keys

Before deploying, generate your operator keys:

docker run --rm -it 'ssvlabs/ssv-node:latest' /go/bin/ssvnode generate-operator-keys

This will output your operator’s public key (pk) and private key (sk). Save these securely.

The raw format is NOT recommended for production use as it can expose sensitive data. See the Security Guide for encrypted keystore setup.

Single Node Deployment

Step 1: Create Configuration File

Create config directory

mkdir -p ~/ssv-node
cd ~/ssv-node

Create config.yaml

Create a config.yaml file with the following content:

global:
  # Console log level (debug, info, warn, error, fatal, panic)
  LogLevel: info
  # Debug logs file path
  LogFilePath: ./data/debug.log

db:
  # Path to a persistent directory to store the node's database
  Path: ./data/db

ssv:
  # The SSV network to join
  # Mainnet = Network: mainnet (default)
  # Testnet = Network: holesky
  Network: mainnet

eth2:
  # HTTP URL of the Beacon node to connect to
  BeaconNodeAddr: http://your-beacon-node:5052

eth1:
  # WebSocket URL of the Eth1 node to connect to
  ETH1Addr: ws://your-eth1-node:8546

p2p:
  # External IP address of the node (optional, auto-detected if not set)
  # HostAddress: YOUR_PUBLIC_IP
  # TCP port for P2P communication
  # TcpPort: 13001
  # UDP port for P2P discovery
  # UdpPort: 12001

# Operator private key (generated in previous step)
OperatorPrivateKey: YOUR_OPERATOR_PRIVATE_KEY

# Enable metrics monitoring
MetricsAPIPort: 15000

# Enable SSV API (keep private)
# SSVAPIPort: 16000

Start the node

Run the Docker container:

docker run -d \
  --restart unless-stopped \
  --name ssv_node \
  -e CONFIG_PATH=./config.yaml \
  -p 13001:13001 \
  -p 12001:12001/udp \
  -p 15000:15000 \
  -v $(pwd)/config.yaml:/config.yaml \
  -v $(pwd)/data:/data \
  --log-opt max-size=500m \
  --log-opt max-file=10 \
  'ssvlabs/ssv-node:latest' \
  make BUILD_PATH=/go/bin/ssvnode start-node

View logs

docker logs ssv_node --follow

Environment Variables

Key environment variables used by the SSV Node container:

Variable	Description	Default
`CONFIG_PATH`	Path to configuration file	`./config.yaml`
`GODEBUG`	Go runtime debug flags	`netdns=go`

Volume Mounts

The container requires the following volume mounts:

Host Path	Container Path	Purpose
`./config.yaml`	`/config.yaml`	Configuration file
`./data`	`/data`	Database and logs

Port Mappings

Port	Protocol	Purpose
13001	TCP	P2P communication
12001	UDP	P2P discovery
15000	TCP	Metrics API
16000	TCP	SSV API (optional)

Docker Compose Deployment

For production deployments, Docker Compose provides better management and configuration.

Basic Configuration

Create a docker-compose.yaml file:

version: "3.8"

services:
  ssv-node:
    image: ssvlabs/ssv-node:latest
    container_name: ssv-node
    restart: unless-stopped
    command: make BUILD_PATH=/go/bin/ssvnode start-node
    environment:
      CONFIG_PATH: ./config.yaml
    ports:
      - "13001:13001"      # P2P TCP
      - "12001:12001/udp"  # P2P UDP
      - "15000:15000"      # Metrics
    volumes:
      - ./config.yaml:/config.yaml
      - ./data:/data
    logging:
      driver: "json-file"
      options:
        max-size: "500m"
        max-file: "10"
    networks:
      - ssv-network

networks:
  ssv-network:
    driver: bridge

Starting the Node

Start the service

docker-compose up -d

Check status

docker-compose ps

View logs

docker-compose logs -f ssv-node

Stop the service

docker-compose down

Multi-Node Local Cluster

For development or testing, you can run a multi-node SSV cluster locally.

Multi-Node Docker Compose Configuration

version: "3.8"

x-base: &default-base
  image: ssvlabs/ssv-node:latest
  command: make BUILD_PATH=/go/bin/ssvnode start-node
  restart: unless-stopped
  networks:
    - ssv-cluster
  environment:
    CONFIG_PATH: ./config/config.yaml

services:
  ssv-node-1:
    <<: *default-base
    container_name: ssv-node-1
    environment:
      CONFIG_PATH: ./config/config.yaml
      SHARE_CONFIG: ./config/share1.yaml
    ports:
      - "16001:16000"
      - "17001:15001"
    volumes:
      - ./data/ssv-node-1:/data
      - ./config:/config

  ssv-node-2:
    <<: *default-base
    container_name: ssv-node-2
    environment:
      CONFIG_PATH: ./config/config.yaml
      SHARE_CONFIG: ./config/share2.yaml
    ports:
      - "16002:16000"
      - "17002:15002"
    volumes:
      - ./data/ssv-node-2:/data
      - ./config:/config

  ssv-node-3:
    <<: *default-base
    container_name: ssv-node-3
    environment:
      CONFIG_PATH: ./config/config.yaml
      SHARE_CONFIG: ./config/share3.yaml
    ports:
      - "16003:16000"
      - "17003:15003"
    volumes:
      - ./data/ssv-node-3:/data
      - ./config:/config

  ssv-node-4:
    <<: *default-base
    container_name: ssv-node-4
    environment:
      CONFIG_PATH: ./config/config.yaml
      SHARE_CONFIG: ./config/share4.yaml
    ports:
      - "16004:16000"
      - "17004:15004"
    volumes:
      - ./data/ssv-node-4:/data
      - ./config:/config

networks:
  ssv-cluster:
    driver: bridge
    name: ssv-cluster

For multi-node clusters, add the following to your config.yaml:

p2p:
  Discovery: mdns

LocalEventsPath: ./config/events.yaml

Updating the Node

Check Current Version

docker run --rm -it 'ssvlabs/ssv-node:latest' /go/bin/ssvnode version

Update to Latest Version

Stop and remove the container

docker rm -f ssv_node

Pull the latest image

docker pull ssvlabs/ssv-node:latest

Restart the container

Run the same docker run command from the deployment step.

For Docker Compose:

docker-compose down
docker-compose pull
docker-compose up -d

Health Checks

Add health checks to your Docker Compose configuration:

services:
  ssv-node:
    # ... other configuration
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:15000/metrics"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

Troubleshooting

Container Won’t Start

Check logs:
```
docker logs ssv_node
```

Verify configuration file syntax:

docker run --rm -v $(pwd)/config.yaml:/config.yaml ssvlabs/ssv-node:latest cat /config.yaml

Ensure ports are not in use:
```
netstat -tuln | grep -E '12001|13001'
```

Network Issues

Verify firewall rules allow UDP 12001 and TCP 13001
Check if HostAddress is correctly set in config.yaml
Ensure execution and consensus node URLs are accessible

Permission Issues

If you encounter permission errors with volume mounts:

sudo chown -R 1000:1000 ./data

Overview

Getting Started

Node Operations

Core Concepts

Deployment

Monitoring

Docker Deployment

Overview

Prerequisites

Docker Image

Generating Operator Keys

Single Node Deployment

Step 1: Create Configuration File

Environment Variables

Volume Mounts

Port Mappings

Docker Compose Deployment

Basic Configuration

Starting the Node

Multi-Node Local Cluster

Updating the Node

Check Current Version

Update to Latest Version

Health Checks

Troubleshooting

Container Won’t Start

Network Issues

Permission Issues

Next Steps

Build docs developers (and LLMs) love

Overview

Getting Started

Node Operations

Core Concepts

Deployment

Monitoring

​Overview

​Prerequisites

​Docker Image

​Generating Operator Keys

​Single Node Deployment

​Step 1: Create Configuration File

​Environment Variables

​Volume Mounts

​Port Mappings

​Docker Compose Deployment

​Basic Configuration

​Starting the Node

​Multi-Node Local Cluster

​Updating the Node

​Check Current Version

​Update to Latest Version

​Health Checks

​Troubleshooting

​Container Won’t Start

​Network Issues

​Permission Issues

​Next Steps

Build docs developers (and LLMs) love

Overview

Prerequisites

Docker Image

Generating Operator Keys

Single Node Deployment

Step 1: Create Configuration File

Environment Variables

Volume Mounts

Port Mappings

Docker Compose Deployment

Basic Configuration

Starting the Node

Multi-Node Local Cluster

Updating the Node

Check Current Version

Update to Latest Version

Health Checks

Troubleshooting

Container Won’t Start

Network Issues

Permission Issues

Next Steps