mirror of
https://github.com/luxfi/node.git
synced 2026-07-27 03:39:39 +00:00
zeekayandHanzo Dev
51a304804c
Drop the Avalanche-heritage /ext prefix; /v1 is the single canonical route surface (one way, no backward compat). The node's baseURL is the source of truth; clients, SDKs, CLI, indexer, maker, genesis, netrunner, and the k8s/compose/gateway/explorer configs are updated to match. Co-authored-by: Hanzo Dev <dev@hanzo.ai>
200 lines
4.1 KiB
Markdown
200 lines
4.1 KiB
Markdown
# Lux Node Docker Documentation
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
### With Monitoring
|
|
```bash
|
|
docker-compose --profile monitoring up -d
|
|
```
|
|
|
|
## Kubernetes Deployment
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```yaml
|
|
# 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:
|
|
|
|
```yaml
|
|
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):
|
|
|
|
```bash
|
|
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
|
|
```bash
|
|
docker logs luxd
|
|
docker exec luxd tail -f /logs/luxd.log
|
|
```
|
|
|
|
### Access Shell
|
|
```bash
|
|
docker exec -it luxd /bin/bash
|
|
```
|
|
|
|
### Test RPC
|
|
```bash
|
|
# 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. |