node/docker/DOCKER.md

Lux Node Docker Documentation

Quick Start

# Pull the latest image
docker pull ghcr.io/luxfi/node:latest

# Run a single node
docker run -d \
  --name luxd \
  -p 9630:9630 \
  -p 9631:9631 \
  -v luxd-data:/data \
  -e NETWORK_ID=96369 \
  ghcr.io/luxfi/node:latest

Building the Image

# Build locally
docker build -t luxfi/node:local .

# Build and push to GitHub Container Registry
docker build -t ghcr.io/luxfi/node:latest .
docker push ghcr.io/luxfi/node:latest

Environment Variables

Variable	Description	Default
NETWORK_ID	Network ID	96369
HTTP_HOST	HTTP API host	0.0.0.0
HTTP_PORT	HTTP API port	9630
STAKING_PORT	Staking port	9631
LOG_LEVEL	Log level	info
BOOTSTRAP_IPS	Bootstrap node IPs	-
BOOTSTRAP_IDS	Bootstrap node IDs	-
STAKING_KEY_KMS_ID	AWS KMS key ID for staking	-

Volume Mounts

• /data - Persistent data directory
• /logs - Log files
• /keys/staking - Staking certificates (for validators)
• /blockchain-data - Pre-loaded blockchain data (optional)

Docker Compose

Basic Setup

docker-compose up -d

With Monitoring

docker-compose --profile monitoring up -d

Kubernetes Deployment

# Create namespace and deploy
kubectl apply -f k8s/luxd-statefulset.yaml

# Scale replicas
kubectl scale statefulset luxd -n lux-network --replicas=5

# Check status
kubectl get pods -n lux-network

Docker Swarm

# Initialize swarm (if not already)
docker swarm init

# Create secrets
echo "your-staking-key" | docker secret create staking_key -
echo "your-staking-cert" | docker secret create staking_cert -

# Deploy stack
docker stack deploy -c docker-stack.yml lux

# Check services
docker service ls
docker service ps lux_luxd

Security Best Practices

1. Staking Keys Management

Never store staking keys in environment variables for production. Use one of:

• AWS KMS: Set STAKING_KEY_KMS_ID
• Docker Secrets: Mount via secrets (Swarm mode)
• Kubernetes Secrets: Use K8s secrets with proper RBAC
• HashiCorp Vault: Integrate with Vault for key management

2. Network Security

# Restrict network access
networks:
  lux-network:
    driver: bridge
    ipam:
      config:
        - chain: 172.20.0.0/16
    internal: true  # No external access

3. Resource Limits

Always set resource limits to prevent resource exhaustion:

deploy:
  resources:
    limits:
      cpus: '4'
      memory: 8G
    reservations:
      cpus: '2'
      memory: 4G

Monitoring

Prometheus Metrics

The node exposes metrics at http://localhost:9630/v1/metrics

Health Checks

• Liveness: http://localhost:9630/v1/health
• Readiness: http://localhost:9630/v1/info

Grafana Dashboard

Import dashboard from monitoring/grafana/dashboards/luxd.json

Loading Blockchain Data

To use pre-loaded blockchain data (1,082,781 blocks):

docker run -d \
  --name luxd \
  -p 9630:9630 \
  -v luxd-data:/data \
  -v ./state/cchain:/blockchain-data:ro \
  -e NETWORK_ID=96369 \
  ghcr.io/luxfi/node:latest

The entrypoint script will automatically detect and load the blockchain data on first run.

Troubleshooting

Check Logs

docker logs luxd
docker exec luxd tail -f /logs/luxd.log

Access Shell

docker exec -it luxd /bin/bash

Test RPC

# Check if bootstrapped
curl -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"info.isBootstrapped","params":{"chain":"C"}}' \
  http://localhost:9630/v1/info

# Get block number
curl -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' \
  http://localhost:9630/v1/bc/C/rpc

CI/CD

The GitHub Actions workflow automatically:

1. Builds the Docker image on push to main
2. Tags with version, branch, and SHA
3. Pushes to GitHub Container Registry
4. Generates SBOM for security scanning
5. Supports multi-platform builds (amd64, arm64)

License

See LICENSE file in the repository root.