Docker Development

Prerequisites

macOS

Install Docker Desktop from docs.docker.com/desktop/install/mac-install/

Ubuntu

Install Docker Engine and Docker Compose:

• Docker: docs.docker.com/engine/install/ubuntu/
• Docker Compose: docs.docker.com/compose/install/other/

Four-Node Local Cluster

The standard development setup runs a four-validator Paxeer cluster on a private network (192.168.10.0/24).

Start Cluster

# Build and start (first time or after code changes)
make docker-cluster-start

# Quick start (skip build if paxd binary exists)
make docker-cluster-start-skipbuild

This launches four pax-node-* containers. Genesis files and logs are generated under build/generated/.

Node Ports

Monitor Logs

# Tail logs for node 0
tail -f build/generated/logs/paxd-0.log

# View all logs
ls -l build/generated/logs/

SSH Into Container

# List containers
docker ps -a

# SSH into a node
docker exec -it pax-node-0 /bin/bash

Environment Variables

The cluster supports environment variable configuration:

Single Node (Not Recommended)

For minimal testing only:

make build-docker-node && make run-local-node

The four-node cluster is preferred for realistic consensus behavior.

Compose Files

Monitoring with Prometheus & Grafana

Start the cluster with monitoring containers:

# Start cluster + monitoring together
make docker-cluster-start-monitoring

# Stop cluster + monitoring together
make docker-cluster-stop-monitoring

Or run monitoring scripts independently:

# Start Prometheus
./docker/monitornode/scripts/start-prometheus.sh

# Start Grafana
./docker/monitornode/scripts/start-grafana.sh

# Stop
./docker/monitornode/scripts/stop-prometheus.sh
./docker/monitornode/scripts/stop-grafana.sh

Access UIs

• Grafana: http://localhost:3000 (login: admin / admin)
• Prometheus: http://localhost:9090

State Sync RPC Node

Test state-sync by starting an additional RPC node that syncs from the four-node cluster:

# Prerequisite: Start a 4-node cluster
make docker-cluster-start

# Wait until block height exceeds 500 (configurable via app.toml)
paxd status | jq

# Start state-sync RPC node
make run-rpc-node

The RPC node bootstraps from a recent snapshot instead of replaying full history.

Fast Iteration & Local Development

Docker mounts local source directories, so you can edit code and rebuild without re-pulling dependencies:

1. Edit code under paxeer-network/ (modules, consensus, SDK, storage, WASM)
2. Rebuild the node image: make build-docker-node
3. Restart the cluster: make docker-cluster-start

No go.mod replacements or sibling repositories required. The monorepo includes all dependencies.

Volumes

The compose files mount:

• $PROJECT_HOME → /pax-protocol/pax-chain (source tree)
• $GO_PKG_PATH/mod → /root/go/pkg/mod (Go module cache)
• $GOCACHE → /root/.cache/go-build (Go build cache)

Deployment Scripts

Each node type has a multi-step initialization flow:

Local Node

• step0_build.sh — Build paxd binary
• step1_configure_init.sh — Initialize node configuration
• step2_genesis.sh — Generate genesis file
• step3_add_validator_to_genesis.sh — Add validator to genesis
• step4_config_override.sh — Override config files (ports, peers)
• step5_start_pax.sh — Start paxd
• deploy.sh — Orchestrates all steps

RPC Node

• step0_build.sh — Build paxd
• step1_configure_init.sh — Initialize for state-sync
• step2_start_pax.sh — Start with state-sync enabled
• deploy.sh — Orchestrates RPC node setup

Docker Image

The cluster uses the pax-chain/localnode image built from paxeer-network/Dockerfile. Platform defaults to linux/amd64 but can be overridden with DOCKER_PLATFORM.

Network Configuration

The cluster creates a localnet bridge network with subnet 192.168.10.0/24. Each node has a static IP for deterministic peer configuration.