> For the complete documentation index, see [llms.txt](https://quantumwing.gitbook.io/quantumwing/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://quantumwing.gitbook.io/quantumwing/deployment/production-setup.md).

# Production Setup

Production deployment guide with multiple deployment options

## Overview

QuantumWing supports **4 production deployment methods**, each optimized for different use cases:

| Method          | Use Case                   | Complexity  | Nodes         |
| --------------- | -------------------------- | ----------- | ------------- |
| **Development** | Local testing, development | ⭐ Simple    | 1 (3 layers)  |
| **Production**  | Standalone validators      | ⭐⭐ Medium   | 3 validators  |
| **Multi-Node**  | P2P network testing        | ⭐⭐ Medium   | 3 nodes + DHT |
| **Docker/K8s**  | Enterprise production      | ⭐⭐⭐ Complex | 5+ nodes      |

## Prerequisites

### All Methods

* Linux/macOS system
* 8GB RAM minimum (32GB recommended for multi-node)
* 50GB disk space (SSD recommended)
* Go 1.21+ installed

### Docker/Kubernetes

* Docker 20.10+ and Docker Compose 2.0+
* Kubernetes 1.24+ (for K8s deployment)
* kubectl configured
* 500GB SSD storage

## Method 1: Development (Three-Layer)

**Best for**: Local development, testing smart contracts, learning QuantumWing

### Quick Start

```bash
git clone https://github.com/quantumwing/protocol
cd protocol

# Build binaries
make build

# Start three-layer architecture
./scripts/secure-three-layer.sh
```

### What This Does

1. **Execution Layer** (Port 8546)
   * Transaction processing
   * QWVM smart contract execution
   * State management (BadgerDB)
2. **Beacon Chain** (Port 8080)
   * Proof of Randomness consensus
   * Validator coordination
   * Block finality
3. **Validators** (3 instances)
   * production-validator-0
   * production-validator-1
   * production-validator-2

### Verification

```bash
# Check execution layer
curl http://localhost:8546/health

# Check beacon chain
curl http://localhost:8080/api/v1/beacon/info | jq '.'

# Check blockchain height
curl http://localhost:8080/api/v1/blockchain/status | jq '.height'

# Monitor logs
tail -f logs/execution/execution.log
tail -f logs/beacon/beacon.log
tail -f logs/validators/production-validator-0.log
```

### Directory Structure

```
protocol/
├── logs/
│   ├── execution/execution.log
│   ├── beacon/beacon.log
│   └── validators/
│       ├── production-validator-0.log
│       ├── production-validator-1.log
│       └── production-validator-2.log
├── data/
│   ├── execution/      # Transaction pool, state
│   └── beacon/         # Consensus, validator registry
└── wallets/
    └── production-validators/
        ├── validator-0/validator.json
        ├── validator-1/validator.json
        └── validator-2/validator.json
```

## Method 2: Production (Real Validators)

**Best for**: Production deployment with true validator separation

### Setup

```bash
# Run production setup script
./scripts/production-setup.sh
```

### What This Does

**Step 1**: Generate 3 production validator wallets

```bash
# Creates Dilithium Mode 3 key pairs
wallets/production-validators/validator-0/validator.json
wallets/production-validators/validator-1/validator.json
wallets/production-validators/validator-2/validator.json
```

**Step 2**: Create production genesis

```json
{
  "genesis_time": "2026-01-01T10:00:00Z",
  "chain_id": "quantum-production-1",
  "validators": [
    {
      "address": "production-validator-0",
      "public_key": "0x1234...5678",
      "stake": 32,
      "name": "Production Validator 0"
    }
  ]
}
```

**Step 3**: Start beacon coordinator

* No self-validation
* Receives block proposals from external validators
* Verifies Dilithium signatures

**Step 4**: Start 3 external validators

* Each validator runs as separate process
* Submit blocks via REST API
* True separation (not embedded)

### Architecture

```
┌─────────────────────────────────────────┐
│   Beacon Coordinator (Port 8080)        │
│   • NO self-validation                  │
│   • Receives external block proposals   │
│   • Verifies Dilithium signatures       │
└───────────────┬─────────────────────────┘
                │ REST API
        ┌───────┼───────┬────────┐
        │       │       │        │
        ▼       ▼       ▼        ▼
    ┌───────┬───────┬───────┐
    │ Val 0 │ Val 1 │ Val 2 │  External Validators
    └───────┴───────┴───────┘  (Separate Processes)
```

### Monitoring

```bash
# Check validator registration
curl http://localhost:8080/api/v1/validators | jq '.'

# Check slot proposers
for slot in {0..5}; do
  curl "http://localhost:8080/api/v1/beacon/slots/$slot/proposer" | jq -r '.proposer'
done

# Monitor validator activity
tail -f logs/validators/production-validator-0.log | grep "Creating and proposing block"

# Check beacon received external blocks
tail -f logs/beacon/coordinator.log | grep "Received block proposal from external validator"
```

### Process Management

```bash
# Stop all processes
pkill -f quantum-wing

# Stop specific validator
pkill -f "validator-id production-validator-0"

# Restart beacon
./build/quantum-wing-blockchain start \
    --genesis genesis/production-genesis.json \
    --data-dir data/production/beacon \
    --api-port 8080
```

## Method 3: Multi-Node P2P Network

**Best for**: Testing P2P networking, DHT discovery, multi-region deployment

### Setup

```bash
./scripts/start-3node-dht-testnet.sh
```

### Network Topology

```
Node 1 (Bootstrap Seed)
├─ Execution: localhost:8546
├─ Beacon: localhost:8080
├─ P2P: 9000 (execution), 9003 (beacon)
└─ Validators: 3 production validators

Node 2
├─ Execution: localhost:8547
├─ Beacon: localhost:8081
├─ P2P: 9001, 9004
└─ Bootstrap: Node 1

Node 3
├─ Execution: localhost:8548
├─ Beacon: localhost:8082
├─ P2P: 9002, 9005
└─ Bootstrap: Node 1 → Discovers Node 2 via DHT ✅
```

### DHT Peer Discovery Test

**Goal**: Verify Node 3 discovers Node 2 through DHT (not bootstrap)

```bash
# Wait 30 seconds for discovery
sleep 30

# Check Node 3 discovered Node 2
grep "Discovered peer via DHT" logs/node3/beacon/beacon.log

# Expected output:
# ✅ Discovered peer via DHT: QmXYZ... (node-2)
```

### Verification

```bash
# Check Node 1 peers
curl http://localhost:8080/api/v1/p2p/peers | jq '.peers | length'
# Expected: 2 (Node 2, Node 3)

# Check Node 2 peers
curl http://localhost:8081/api/v1/p2p/peers | jq '.peers | length'
# Expected: 2 (Node 1, Node 3)

# Check Node 3 peers
curl http://localhost:8082/api/v1/p2p/peers | jq '.peers | length'
# Expected: 2 (Node 1, Node 2)

# Check blockchain sync
for port in 8080 8081 8082; do
  echo "Node $((port - 8080)):"
  curl -s "http://localhost:$port/api/v1/blockchain/status" | jq '.height'
done
# All nodes should have same height
```

### Multi-Region Deployment

For geographically distributed nodes:

```bash
# Node 1 (US-East)
./build/quantum-wing-blockchain start \
  --listen /ip4/0.0.0.0/tcp/30303 \
  --advertise /ip4/54.123.45.67/tcp/30303

# Node 2 (EU-West)
./build/quantum-wing-blockchain start \
  --bootstrap /ip4/54.123.45.67/tcp/30303 \
  --listen /ip4/0.0.0.0/tcp/30303

# Node 3 (APAC)
./build/quantum-wing-blockchain start \
  --bootstrap /ip4/54.123.45.67/tcp/30303 \
  --listen /ip4/0.0.0.0/tcp/30303
```

## Method 4: Docker & Kubernetes

**Best for**: Enterprise production, high availability, auto-scaling

### Docker Compose (5 Nodes)

#### 1. Generate Genesis

```bash
cd deployments
mkdir -p genesis wallets

# Generate production genesis
quantum-wing genesis init \
  --chain-id mainnet-1 \
  --validators 3 \
  --output genesis/genesis.json
```

#### 2. Generate Validator Wallets

```bash
for i in 0 1 2; do
  quantum-wing wallet create \
    --name validator-$i \
    --output wallets/validator-$i.json
done
```

#### 3. Start Network

```bash
docker-compose -f docker-compose-production.yml up -d
```

#### 4. Verify Deployment

```bash
# Check containers
docker-compose -f docker-compose-production.yml ps

# Expected output:
# qw-node-0       Up 5 minutes   0.0.0.0:8080->8080/tcp
# qw-node-1       Up 5 minutes   0.0.0.0:8081->8080/tcp
# qw-node-2       Up 5 minutes   0.0.0.0:8082->8080/tcp
# qw-node-3       Up 5 minutes   0.0.0.0:8083->8080/tcp
# qw-node-4       Up 5 minutes   0.0.0.0:8084->8080/tcp
# qw-validator-0  Up 5 minutes
# qw-validator-1  Up 5 minutes
# qw-validator-2  Up 5 minutes
# prometheus      Up 5 minutes   0.0.0.0:9090->9090/tcp
# grafana         Up 5 minutes   0.0.0.0:3000->3000/tcp
```

#### 5. Access Services

* **API (Node 0)**: <http://localhost:8080>
* **Grafana**: <http://localhost:3000> (admin/quantum\_secure\_password)
* **Prometheus**: <http://localhost:9090>

### Kubernetes (Scalable)

#### 1. Create Namespace

```bash
kubectl apply -f kubernetes/01-namespace.yaml
```

#### 2. Create Secrets

```bash
# Genesis config
kubectl create secret generic genesis-config \
  --from-file=genesis.json=genesis/genesis.json \
  -n quantum-wing

# Validator wallets
kubectl create secret generic validator-wallets \
  --from-file=validator-0.json=wallets/validator-0.json \
  --from-file=validator-1.json=wallets/validator-1.json \
  --from-file=validator-2.json=wallets/validator-2.json \
  -n quantum-wing

# Grafana password
kubectl create secret generic grafana-admin \
  --from-literal=password='quantum_secure_password' \
  -n quantum-wing
```

#### 3. Deploy Nodes

```bash
# Apply ConfigMap
kubectl apply -f kubernetes/02-configmap.yaml

# Deploy StatefulSet (5 nodes)
kubectl apply -f kubernetes/03-statefulset-nodes.yaml

# Wait for nodes
kubectl wait --for=condition=ready pod \
  -l component=node \
  -n quantum-wing \
  --timeout=5m
```

#### 4. Deploy Validators

```bash
kubectl apply -f kubernetes/04-deployment-validators.yaml
```

#### 5. Expose Services

```bash
# API LoadBalancer
kubectl apply -f kubernetes/05-service-api.yaml

# Get external IP
kubectl get svc quantum-wing-api -n quantum-wing
```

#### 6. Deploy Monitoring

```bash
kubectl apply -f kubernetes/06-monitoring.yaml

# Access Grafana
kubectl port-forward -n quantum-wing svc/grafana 3000:3000
```

### Kubernetes Scaling

```bash
# Scale to 10 nodes
kubectl scale statefulset quantum-wing-node --replicas=10 -n quantum-wing

# Scale to 5 validators
kubectl scale deployment quantum-wing-validator --replicas=5 -n quantum-wing
```

## Monitoring & Observability

### Metrics

All deployment methods expose Prometheus metrics:

```bash
# Node metrics
curl http://localhost:9090/metrics

# Key metrics:
# - blockchain_blocks_total
# - blockchain_transactions_total
# - validator_proposals_total
# - p2p_peers_connected
# - qwvm_gas_used_total
```

### Grafana Dashboards

Access Grafana (Docker/K8s):

* URL: <http://localhost:3000>
* Username: `admin`
* Password: `quantum_secure_password`

**Pre-configured dashboards**:

1. **QuantumWing Overview**
   * TPS (transactions per second)
   * Block production rate
   * Validator uptime
   * P2P peer count
2. **Consensus Metrics**
   * Slot progression
   * Finality time
   * Attestation participation
   * RANDAO reveals
3. **Performance**
   * Gas usage
   * State size
   * API latency
   * P2P bandwidth

### Log Aggregation

**Local deployment**:

```bash
# Aggregate all logs
tail -f logs/**/*.log

# Filter by severity
grep "ERROR" logs/**/*.log
grep "WARN" logs/**/*.log
```

**Docker**:

```bash
# View container logs
docker logs qw-node-0 -f

# All containers
docker-compose -f docker-compose-production.yml logs -f
```

**Kubernetes**:

```bash
# Node logs
kubectl logs -n quantum-wing quantum-wing-node-0 -f

# Validator logs
kubectl logs -n quantum-wing -l component=validator -f

# All pods
kubectl logs -n quantum-wing --all-containers=true -f
```

## Security Hardening

### Network Security

```bash
# Firewall rules (ufw example)
sudo ufw allow 8080/tcp  # Beacon API
sudo ufw allow 8546/tcp  # Execution API
sudo ufw allow 30303/tcp # P2P
sudo ufw deny 9090/tcp   # Metrics (internal only)
```

### TLS/SSL Setup

```bash
# Generate self-signed certificate
openssl req -x509 -newkey rsa:4096 \
  -keyout key.pem -out cert.pem \
  -days 365 -nodes \
  -subj "/CN=quantumwing.example.com"

# Start with TLS
./build/quantum-wing-blockchain start \
  --tls-cert cert.pem \
  --tls-key key.pem

### Application-Layer Encryption (Kyber)

- Encrypted Messaging via Kyber-1024 initializes automatically with the P2P network; no extra flags required.
- Transport-level PQ‑TLS will be optional behind a feature flag with classical TLS fallback (roadmap item).
```

### Secret Management

**Environment variables**:

```bash
export QW_VALIDATOR_KEY="<dilithium-private-key>"
export QW_API_KEY="<api-secret>"
```

**Kubernetes secrets**:

```bash
kubectl create secret generic validator-keys \
  --from-literal=private-key="<key>" \
  -n quantum-wing
```

## Backup & Recovery

### Database Backup

```bash
# Stop node
pkill -f quantum-wing-blockchain

# Backup BadgerDB
tar -czf backup-$(date +%Y%m%d).tar.gz data/

# Restart node
./build/quantum-wing-blockchain start ...
```

### Genesis Backup

```bash
# Always keep genesis file
cp genesis/production-genesis.json /backup/genesis-$(date +%Y%m%d).json
```

### Wallet Backup

```bash
# Backup validator wallets (CRITICAL)
tar -czf wallets-backup-$(date +%Y%m%d).tar.gz wallets/
# Store in secure location (encrypted USB, vault, etc.)
```

### Disaster Recovery

```bash
# 1. Stop all nodes
pkill -f quantum-wing

# 2. Restore data
tar -xzf backup-20251028.tar.gz

# 3. Verify genesis hash
quantum-wing genesis hash genesis/production-genesis.json

# 4. Restart network
./scripts/production-setup.sh
```

## Troubleshooting

### Node Won't Start

```bash
# Check logs
tail -f logs/beacon/beacon.log

# Common issues:
# - Port already in use (kill process on port 8080)
# - Invalid genesis file (verify with `quantum-wing genesis validate`)
# - Missing wallet files (check wallets/ directory)
# - Insufficient disk space (df -h)
```

### Validators Not Producing Blocks

```bash
# Check validator registration
curl http://localhost:8080/api/v1/validators | jq '.'

# Verify wallet loaded
grep "Loaded validator wallet" logs/validators/production-validator-0.log

# Check beacon receiving proposals
grep "Received block proposal" logs/beacon/coordinator.log
```

### Network Partition

```bash
# Check P2P connectivity
curl http://localhost:8080/api/v1/p2p/peers | jq '.peers | length'

# Should have 2+ peers for 3-node setup

# Force reconnect
pkill -HUP quantum-wing-blockchain
```

### High Memory Usage

```bash
# Check process memory
ps aux | grep quantum-wing

# Prune old blocks (keep last 100k)
./build/quantum-wing-blockchain prune --keep 100000

# Restart with memory limit
ulimit -m 8388608  # 8GB
./build/quantum-wing-blockchain start ...
```

## Production Checklist

Before going live:

* [ ] Genesis file generated and validated
* [ ] Validator wallets created and backed up
* [ ] Firewall rules configured
* [ ] TLS/SSL certificates installed

### Application-Layer Encryption (Kyber)

* [ ] Encrypted Messaging using Kyber-1024 is initialized automatically with the P2P network; no extra configuration required.
* [ ] Transport‑level PQ‑TLS remains a roadmap item; plan to ship behind a feature flag with classical TLS fallback for compatibility.
* [ ] Monitoring dashboards set up
* [ ] Alert rules configured (PagerDuty/Opsgenie)
* [ ] Backup system tested
* [ ] Load testing completed (1000+ TPS)
* [ ] Disaster recovery plan documented
* [ ] On-call rotation established

## Next Steps

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>📊 Monitoring</strong></td><td>Set up Prometheus/Grafana</td><td><a href="/quantumwing/operations/monitoring.md">Monitoring</a></td></tr><tr><td><strong>🔒 Security</strong></td><td>Harden production deployment</td><td><a href="/quantumwing/deployment/security.md">Security Hardening</a></td></tr><tr><td><strong>⚙️ Performance</strong></td><td>Tune for high throughput</td><td><a href="/quantumwing/operations/performance.md">Performance Tuning</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://quantumwing.gitbook.io/quantumwing/deployment/production-setup.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.