Docker Deployment

Docker provides an easy way to deploy and manage Viction nodes without dealing with complex dependency management. This guide covers both building and running Viction nodes in Docker containers.

Quick Start

The fastest way to get started is using the official pre-built Docker image:

docker run -d --name viction \
  -v "$(pwd)/data:/tomochain/data" \
  -v "$(pwd)/keystore:/tomochain/keystore" \
  -v "$(pwd)/password:/tomochain/password" \
  -p 8545:8545 \
  -p 8546:8546 \
  -p 30303:30303 \
  -e IDENTITY=my-node \
  -e NETWORK_ID=88 \
  buildonviction/node:v2.5.1

Building the Docker Image

To build the Viction node Docker image from source:

Clone the repository

git clone https://github.com/BuildOnViction/victionchain.git
cd victionchain

Build the image

docker build --file Dockerfile.node -t "buildonviction/node:v2.5.1" .

This builds a multi-stage Docker image that:

Compiles the tomo binary using Go 1.18
Creates a minimal Alpine-based runtime image
Includes the entrypoint script and genesis files

Verify the build

docker images | grep buildonviction

You should see your newly built image listed.

Environment Variables

The Docker container is configured using environment variables. Here’s the complete reference:

Network Configuration

NETWORK_ID

string

default:"88"

Network identifier:

88: Viction Mainnet
89: Viction Testnet

-e NETWORK_ID=88

IDENTITY

string

default:"unnamed_xxxxxx"

Your node’s name. If not set, a random name is generated.

-e IDENTITY="my-viction-node"

GENESIS_PATH

string

Path to a custom genesis JSON file. If not set, uses the default genesis for the network ID.

-e GENESIS_PATH="/tomochain/custom-genesis.json"

BOOTNODES

string

Comma-separated list of enode URLs for bootstrap. Uses default bootnodes if not set.

-e BOOTNODES="enode://[email protected]:30303,enode://[email protected]:30303"

EXTIP

string

Your external IP address. Only use if you have trouble connecting to peers.

-e EXTIP="203.0.113.1"

P2P_PORT

string

default:"30303"

P2P port for peer connections. Must map host port to the same value.

-e P2P_PORT=30303
-p 30303:30303

MAX_PEERS

string

default:"25"

Maximum number of peers. Set to 0 to disable P2P.

-e MAX_PEERS=25

Sync and Performance

SYNC_MODE

string

default:"full"

Blockchain sync mode:

fast: Fast synchronization
full: Full synchronization
light: Light client mode

-e SYNC_MODE=full

TXPOOL_GLSLOTS

string

default:"3072"

Maximum number of executable transaction slots for all accounts.

-e TXPOOL_GLSLOTS=3072

TXPOOL_GLQUEUE

string

default:"768"

Maximum number of non-executable transaction slots for all accounts.

-e TXPOOL_GLQUEUE=768

Account Management

PRIVATE_KEY

string

Private key in plain text to import into keystore. Use this OR provide keystore files, not both.

-e PRIVATE_KEY="0x1234567890abcdef..."

Passing private keys via environment variables is convenient but less secure. For production, use mounted keystore files.

PASSWORD

string

Password for encrypting/decrypting account. Can also mount password file to /tomochain/password.

-e PASSWORD="your-secure-password"

Network Stats

NETSTATS_HOST

string

default:"netstats-server"

Hostname of ethstats service.

-e NETSTATS_HOST=stats.viction.xyz

NETSTATS_PORT

string

default:"3000"

Port of ethstats service.

-e NETSTATS_PORT=443

WS_SECRET

string

Secret for ethstats service. If not set, node won’t report to netstats.

-e WS_SECRET="getty-site-pablo-auger-room-sos-blair-shin-whiz-delhi"

Advanced Options

DEBUG_MODE

string

Enable archive mode and debug APIs. Set to any non-empty value to enable.

-e DEBUG_MODE=1

Enables:

--gcmode archive
--rpcapi db,eth,net,web3,debug,posv

STORE_REWARD

string

Enable reward snapshots for each epoch. Requires DEBUG_MODE or archive mode.

-e STORE_REWARD=1

ANNOUNCE_TXS

string

Always commit transactions. Set to any non-empty value to enable.

-e ANNOUNCE_TXS=1

VERBOSITY

number

default:"3"

Logging verbosity (1-5).

-e VERBOSITY=3

RPC_TIMEOUT

number

Timeout for RPC HTTP handlers in seconds.

-e RPC_TIMEOUT=120

Volume Mounts

The Docker container expects several mounted volumes:

Data Directory

Mount point: /tomochain/dataStores blockchain data and state.

-v "$(pwd)/data:/tomochain/data"

Keystore

Mount point: /tomochain/keystoreStores encrypted account keys.

-v "$(pwd)/keystore:/tomochain/keystore"

Password File

Mount point: /tomochain/passwordContains account password.

-v "$(pwd)/password:/tomochain/password"

Exposed Ports

The Docker image exposes three ports:

8545

port

HTTP-RPC endpoint for JSON-RPC API calls

-p 8545:8545

8546

port

WebSocket-RPC endpoint for WebSocket connections

-p 8546:8546

30303

port

P2P port for peer-to-peer communication (TCP and UDP)

-p 30303:30303 -p 30303:30303/udp

Deployment Examples

Full Node (Mainnet)
Masternode
Archive Node
Testnet

docker run -d --name viction-node \
  --restart unless-stopped \
  -v "$(pwd)/data:/tomochain/data" \
  -v "$(pwd)/keystore:/tomochain/keystore" \
  -v "$(pwd)/password:/tomochain/password" \
  -p 8545:8545 \
  -p 8546:8546 \
  -p 30303:30303 \
  -p 30303:30303/udp \
  -e IDENTITY=my-fullnode \
  -e NETWORK_ID=88 \
  -e SYNC_MODE=full \
  -e NETSTATS_HOST=stats.viction.xyz \
  -e NETSTATS_PORT=443 \
  -e WS_SECRET=getty-site-pablo-auger-room-sos-blair-shin-whiz-delhi \
  -e VERBOSITY=3 \
  buildonviction/node:v2.5.1

docker run -d --name viction-masternode \
  --restart unless-stopped \
  -v "$(pwd)/data:/tomochain/data" \
  -v "$(pwd)/keystore:/tomochain/keystore" \
  -v "$(pwd)/password:/tomochain/password" \
  -p 8545:8545 \
  -p 8546:8546 \
  -p 30303:30303 \
  -p 30303:30303/udp \
  -e IDENTITY=my-masternode \
  -e NETWORK_ID=88 \
  -e SYNC_MODE=full \
  -e MAX_PEERS=50 \
  -e NETSTATS_HOST=stats.viction.xyz \
  -e NETSTATS_PORT=443 \
  -e WS_SECRET=getty-site-pablo-auger-room-sos-blair-shin-whiz-delhi \
  -e VERBOSITY=3 \
  buildonviction/node:v2.5.1

The entrypoint script automatically detects if your account is a registered masternode and enables mining.

docker run -d --name viction-archive \
  --restart unless-stopped \
  -v "$(pwd)/data:/tomochain/data" \
  -v "$(pwd)/keystore:/tomochain/keystore" \
  -v "$(pwd)/password:/tomochain/password" \
  -p 8545:8545 \
  -p 8546:8546 \
  -p 30303:30303 \
  -p 30303:30303/udp \
  -e IDENTITY=my-archive \
  -e NETWORK_ID=88 \
  -e SYNC_MODE=full \
  -e DEBUG_MODE=1 \
  -e STORE_REWARD=1 \
  -e VERBOSITY=3 \
  buildonviction/node:v2.5.1

Archive nodes require significantly more disk space. Ensure you have at least 1TB available.

docker run -d --name viction-testnet \
  --restart unless-stopped \
  -v "$(pwd)/data:/tomochain/data" \
  -v "$(pwd)/keystore:/tomochain/keystore" \
  -v "$(pwd)/password:/tomochain/password" \
  -p 8545:8545 \
  -p 8546:8546 \
  -p 30303:30303 \
  -p 30303:30303/udp \
  -e IDENTITY=my-testnet-node \
  -e NETWORK_ID=89 \
  -e SYNC_MODE=full \
  -e VERBOSITY=3 \
  buildonviction/node:v2.5.1

Docker Compose

For easier management, use Docker Compose:

docker-compose.yml

version: '3.8'

services:
  viction-node:
    image: buildonviction/node:v2.5.1
    container_name: viction-node
    restart: unless-stopped
    ports:
      - "8545:8545"
      - "8546:8546"
      - "30303:30303"
      - "30303:30303/udp"
    volumes:
      - ./data:/tomochain/data
      - ./keystore:/tomochain/keystore
      - ./password:/tomochain/password
    environment:
      - IDENTITY=my-viction-node
      - NETWORK_ID=88
      - SYNC_MODE=full
      - MAX_PEERS=25
      - NETSTATS_HOST=stats.viction.xyz
      - NETSTATS_PORT=443
      - WS_SECRET=getty-site-pablo-auger-room-sos-blair-shin-whiz-delhi
      - VERBOSITY=3
    logging:
      driver: "json-file"
      options:
        max-size: "100m"
        max-file: "10"

Start the node:

docker-compose up -d

View logs:

docker-compose logs -f

Stop the node:

docker-compose down

Entrypoint Script Details

The Docker image uses an entrypoint script (docker/tomochain/entrypoint.sh) that:

Processes environment variables

Converts environment variables to command-line flags and handles file-based configuration.

Initializes blockchain

If no blockchain data exists, initializes with the appropriate genesis block (mainnet or testnet).

Manages accounts

Imports private key if PRIVATE_KEY is set
Creates password file if needed
Unlocks the first available account

Configures networking

Sets up bootnodes, NAT, and ethstats based on environment variables.

Starts the node

Launches tomo with all configured parameters:

RPC enabled on 0.0.0.0:8545
WebSocket enabled on 0.0.0.0:8546
P2P on configured port
CORS and virtual hosts set to ”*” for development

Container Management

View Logs

docker logs -f viction-node

Access Container Shell

docker exec -it viction-node sh

Check Sync Status

docker exec viction-node sh -c 'curl -X POST --data '"'"'{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}'"'"' -H "Content-Type: application/json" http://localhost:8545'

Stop Container

docker stop viction-node

Remove Container

docker rm viction-node

Update to Latest Version

docker pull buildonviction/node:v2.5.1
docker stop viction-node
docker rm viction-node
# Run the docker run command again with the same parameters

Production Best Practices

Data Persistence

Always use named volumes or bind mounts
Regularly backup keystore and data directories
Use volume drivers for cloud storage
Monitor disk space usage

Resource Limits

Set resource constraints:

--memory="4g" \
--cpus="2.0" \
--storage-opt size=500G

Security

Don’t expose RPC publicly without authentication
Use firewall rules to restrict access
Rotate credentials regularly
Use Docker secrets for sensitive data

Monitoring

Use --restart unless-stopped for auto-restart
Configure log rotation
Monitor container health
Set up alerts for downtime

Troubleshooting

Container keeps restarting

Check logs:

docker logs viction-node

Common issues:

Invalid password file
Missing keystore files
Insufficient disk space
Port already in use

Cannot connect to RPC

Verify:

Container is running: docker ps
Ports are mapped: docker port viction-node
Firewall allows connections
RPC endpoint is accessible from host

Slow sync performance

Optimize:

Increase container memory limit
Use SSD storage
Check network bandwidth
Consider using fast sync mode

High disk usage

Solutions:

Use --gcmode full instead of archive
Disable --store-reward if not needed
Set up log rotation
Prune Docker system: docker system prune

Multi-Node Setup

For advanced users running multiple nodes:

docker-compose.multi.yml

version: '3.8'

services:
  mainnet-node:
    image: buildonviction/node:v2.5.1
    container_name: viction-mainnet
    restart: unless-stopped
    ports:
      - "8545:8545"
      - "30303:30303"
    volumes:
      - ./mainnet/data:/tomochain/data
      - ./mainnet/keystore:/tomochain/keystore
      - ./mainnet/password:/tomochain/password
    environment:
      - IDENTITY=mainnet-node
      - NETWORK_ID=88

  testnet-node:
    image: buildonviction/node:v2.5.1
    container_name: viction-testnet
    restart: unless-stopped
    ports:
      - "8546:8545"
      - "30304:30303"
    volumes:
      - ./testnet/data:/tomochain/data
      - ./testnet/keystore:/tomochain/keystore
      - ./testnet/password:/tomochain/password
    environment:
      - IDENTITY=testnet-node
      - NETWORK_ID=89
      - P2P_PORT=30303

Get Started

Core Concepts

Node Operations

Features

Development

Operations

​Quick Start

​Building the Docker Image

​Environment Variables

​Network Configuration

​Sync and Performance

​Account Management

​Network Stats

​Advanced Options

​Volume Mounts

Data Directory

Keystore

Password File

​Exposed Ports

​Deployment Examples

​Docker Compose

​Entrypoint Script Details

​Container Management

​View Logs

​Access Container Shell

​Check Sync Status

​Stop Container

​Remove Container

​Update to Latest Version

​Production Best Practices

Data Persistence

Resource Limits

Security

Monitoring

​Troubleshooting

​Multi-Node Setup

​Next Steps

Configuration Reference

Running a Full Node

Build docs developers (and LLMs) love

Quick Start

Building the Docker Image

Environment Variables

Network Configuration

Sync and Performance

Account Management

Network Stats

Advanced Options

Volume Mounts

Exposed Ports

Deployment Examples

Docker Compose

Entrypoint Script Details

Container Management

View Logs

Access Container Shell

Check Sync Status

Stop Container

Remove Container

Update to Latest Version

Production Best Practices

Troubleshooting

Multi-Node Setup

Next Steps