Skip to content

docker.md

Latest commit

 

History

History
262 lines (191 loc) · 6.25 KB

docker.md

File metadata and controls

262 lines (191 loc) · 6.25 KB
Raw

Docker Deployment

VIZ Ledger ships Docker images for different deployment profiles. All use a two-stage build: the builder stage compiles the binary; the runtime stage contains only the binary and configuration.

Available Images

Dockerfile Tag Description
Dockerfile-production latest Full mainnet node (Release, all plugins)
Dockerfile-testnet testnet Testnet node (BUILD_TESTNET=ON)

Quick Start

docker run -d \
  --name vizd \
  --restart unless-stopped \
  -p 2001:2001 \
  -p 8090:8090 \
  -p 8091:8091 \
  -v /data/vizd:/var/lib/vizd \
  vizblockchain/vizd:latest

Follow logs:

docker logs -f vizd

Volumes

Container path Purpose
/var/lib/vizd Blockchain data, shared memory, block log
/etc/vizd Configuration files

Always mount /var/lib/vizd to persist state across container restarts.

To use a custom config:

docker run -d \
  -v /data/vizd:/var/lib/vizd \
  -v /my/config.ini:/etc/vizd/config.ini \
  vizblockchain/vizd:latest

Environment Variables

The entry script (vizd.sh) reads these environment variables:

Variable Description Example
VIZD_RPC_ENDPOINT Override HTTP RPC endpoint 0.0.0.0:8090
VIZD_P2P_ENDPOINT Override P2P endpoint 0.0.0.0:2001
VIZD_WITNESS_NAME Validator account name (enables block production) alice
VIZD_PRIVATE_KEY Validator signing key in WIF format 5J...
VIZD_EXTRA_OPTS Extra flags appended to the vizd command line --create-snapshot

Ports

Port Protocol Purpose
2001 TCP P2P peer connections
8090 TCP HTTP JSON-RPC
8091 TCP WebSocket JSON-RPC

Validator Node (Docker)

docker run -d \
  --name vizd-validator \
  --restart unless-stopped \
  -p 2001:2001 \
  -v /data/vizd:/var/lib/vizd \
  -e VIZD_WITNESS_NAME=myvalidator \
  -e VIZD_PRIVATE_KEY=5Jxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  vizblockchain/vizd:latest

For validators, do not expose ports 8090/8091 publicly — bind to localhost only:

-e VIZD_RPC_ENDPOINT=127.0.0.1:8090

Testnet Node

docker run -d \
  --name vizd-testnet \
  -p 2001:2001 \
  -p 8090:8090 \
  -v /data/vizd-testnet:/var/lib/vizd \
  vizblockchain/vizd:testnet

Testnet bootstrap

When a node starts without seed nodes, it tries to open a snapshot.json file holding the initial users and their balances. If found, liquid tokens are transferred from the CHAIN_INITIATOR_NAME account to user accounts as vesting (shares).

Initial users and their keys are defined in libraries/protocol/include/graphene/protocol/config.hpp:

  • CHAIN_INITIATOR_NAME (viz) — holds the initial balance.
  • CHAIN_COMMITTEE_ACCOUNT — the initial active validator.

viz keys:

  • private: 5JabcrvaLnBTCkCVFX5r4rmeGGfuJuVp4NAKRNLTey6pxhRQmf4
  • public: VIZ6MyX5QiXAXRZk7SYCiqpi6Mtm8UbHWDFSV8HPpt7FJyahCnc2T

committee keys:

  • private: 5Hw9YPABaFxa2LooiANLrhUK5TPryy8f7v9Y1rk923PuYqbYdfC
  • public: VIZ6Yt7d6LsngBoXQr47aLv97bJVs7jyr7esZTM4UUSpLUf3nbRKS

To ease testing, several additional users are immediately available: alice, bob, charlie, chuck, dan, frank. They all share the same keys:

  • private: 5J9DBCRX5D2ZUUuy9qV2ef9p5sfA3ydHsDs2G531bob7wbEigDJ
  • public: VIZ5zTAE2hiGcqYaDTQeEBqTtPeoWtSNjpznwmbvqJXesrK1Qn3e8

Building Images Locally

# Production
docker build \
  -f share/vizd/docker/Dockerfile-production \
  -t vizd:local \
  .

# Testnet
docker build \
  -f share/vizd/docker/Dockerfile-testnet \
  -t vizd:testnet \
  .

CMake flags per image

Image BUILD_TESTNET
production OFF
testnet ON

CI/CD (GitHub Actions)

The repository ships .github/workflows/docker-main.yml which builds and pushes the production image tagged latest on every push to master.

- name: Build and push
  uses: docker/build-push-action@v2
  with:
    file: share/vizd/docker/Dockerfile-production
    tags: vizblockchain/vizd:latest
    push: true

Resource Sizing

Node type RAM Disk
Full node (mainnet) 8 GB+ 50 GB+
Validator node 4 GB 20 GB
Testnet 4 GB 10 GB

Start with a shared memory size that fits comfortably in RAM. In config.ini:

shared-file-size = 4G

Log Rotation

vizd writes all output to stdout/stderr. Docker's default json-file log driver has no size limit — a crash loop or assertion storm can fill the host disk in minutes (35 GB+ observed in production).

Use the local driver instead. It uses a compact binary format and rotates automatically.

Global config (recommended — protects all containers on the host):

// /etc/docker/daemon.json
{
  "log-driver": "local",
  "log-opts": {
    "max-size": "100m",
    "max-file": "5"
  }
}

Apply with:

sudo systemctl restart docker

Per-container (docker run):

docker run -d \
  --log-driver=local \
  --log-opt max-size=100m \
  --log-opt max-file=5 \
  --name vizd \
  vizblockchain/vizd:latest

Per-container (docker-compose):

services:
  vizd:
    image: vizblockchain/vizd:latest
    logging:
      driver: local
      options:
        max-size: "100m"
        max-file: "5"

With max-file: 5 and max-size: 100m Docker keeps at most 500 MB of logs per container and automatically deletes the oldest file when rotating.

Troubleshooting

Symptom Cause Fix
Container exits immediately Bad config or missing volume docker logs vizd — check for startup errors
Port 8090 unreachable RPC bound to localhost Remove 127.0.0.1: prefix or use reverse proxy
No peers Firewall blocking port 2001 Open port 2001 TCP inbound
Slow sync No snapshot loaded Provide snapshot in volume before first start
Permission denied on /var/lib/vizd Volume ownership mismatch chown -R 1000:1000 /data/vizd
Disk fills up with Docker logs json-file driver has no size limit Configure local driver with max-size/max-file — see Log Rotation