> For the complete documentation index, see [llms.txt](https://docs.neurochain.ai/nc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neurochain.ai/nc/neurochainai-guides/deployment/docker.md).

# Docker Deployment

This guide covers deploying NCN Network v2 using Docker and Docker Compose.

***

## Prerequisites

* Docker 20.10+
* Docker Compose 2.0+
* 8 GB RAM minimum
* 20 GB disk space

### Verify Installation

```bash
docker --version
# Docker version 20.10.x or higher

docker compose version
# Docker Compose version 2.x.x
```

***

## Quick Start

### Start All Services

```bash
cd ncn-network-v2-rs

# Start all services
docker compose up -d

# View logs
docker compose logs -f

# Check status
docker compose ps
```

**Services Started**:

* `ncn-p2p-registry` - P2P Registry on port 50050, 8828
* `ncn-gateway` - Gateway on ports 50051, 8080, 9000
* `ncn-compute-node` - Compute Node

### Stop Services

```bash
# Stop all services
docker compose down

# Stop and remove volumes
docker compose down -v
```

***

## Docker Compose Configuration

### `docker-compose.yml`

```yaml
version: '3.8'

services:
  # P2P Registry Node
  p2p-registry:
    build:
      context: .
      dockerfile: p2p_registry_node/Dockerfile
    container_name: ncn-p2p-registry
    ports:
      - "50050:50050"  # gRPC
      - "8828:8828"    # P2P
    environment:
      - RUST_LOG=info,p2p_registry_node=debug
      - P2P_LISTEN_ADDR=/ip4/0.0.0.0/tcp/8828
      - GRPC_LISTEN_ADDR=0.0.0.0:50050
    volumes:
      - p2p-data:/data
    healthcheck:
      test: ["CMD", "nc", "-z", "localhost", "50050"]
      interval: 10s
      timeout: 5s
      retries: 5

  # Gateway Node
  gateway:
    build:
      context: .
      dockerfile: gateway_node/Dockerfile
    container_name: ncn-gateway
    ports:
      - "50051:50051"  # gRPC
      - "8080:8080"    # HTTP
      - "9000:9000"    # WebSocket
    environment:
      - RUST_LOG=info,gateway_node=debug
      - GRPC_LISTEN_ADDR=0.0.0.0:50051
      - HTTP_LISTEN_ADDR=0.0.0.0:8080
      - WS_LISTEN_ADDR=0.0.0.0:9000
      - REGISTRY_GRPC_ADDR=http://p2p-registry:50050
      - GATEWAY_PRIVATE_KEY=${GATEWAY_PRIVATE_KEY}
      - RPC_URL=${RPC_URL:-http://localhost:8545}
      - CONTRACT_ADDRESS=${CONTRACT_ADDRESS}
    depends_on:
      p2p-registry:
        condition: service_healthy
    volumes:
      - gateway-data:/data

  # Compute Node
  compute-node:
    build:
      context: .
      dockerfile: compute_node/Dockerfile
    container_name: ncn-compute-node
    environment:
      - RUST_LOG=info,compute_node=debug
      - GATEWAY_ADDR=http://gateway:50051
      - SANDBOX_MODE=${SANDBOX_MODE:-disabled}
      - COMPUTE_PRIVATE_KEY=${COMPUTE_PRIVATE_KEY}
    volumes:
      - compute-models:/models
    depends_on:
      gateway:
        condition: service_healthy

volumes:
  p2p-data:
  gateway-data:
  compute-models:
```

***

## Configuration

### Environment Variables

Create a `.env` file in the project root:

```bash
# Blockchain Configuration
RPC_URL=http://localhost:8545
CONTRACT_ADDRESS=0x4361115359E5C0a25c9b2f8Bb71184F010b768ea

# Gateway Configuration
GATEWAY_PRIVATE_KEY=0x...

# Compute Node Configuration
COMPUTE_PRIVATE_KEY=0x...
SANDBOX_MODE=disabled

# Optional
RUST_LOG=info
```

### Using Environment File

```bash
# Start with custom .env file
docker compose --env-file production.env up -d
```

***

## Building Images

### Build All Images

```bash
docker compose build
```

### Build Individual Images

```bash
# P2P Registry
docker build -t ncn-p2p-registry -f p2p_registry_node/Dockerfile .

# Gateway
docker build -t ncn-gateway -f gateway_node/Dockerfile .

# Compute Node
docker build -t ncn-compute-node -f compute_node/Dockerfile .
```

### Build Arguments

```bash
docker build \
  --build-arg RUST_VERSION=1.75 \
  --build-arg PROFILE=release \
  -t ncn-gateway \
  -f gateway_node/Dockerfile .
```

***

## Scaling

### Scale Compute Nodes

```bash
# Run 3 compute nodes
docker compose up -d --scale compute-node=3

# Check all instances
docker compose ps
```

### Using Docker Swarm

```bash
# Initialize swarm
docker swarm init

# Deploy stack
docker stack deploy -c docker-compose.yml ncn

# Scale services
docker service scale ncn_compute-node=5
```

***

## Volumes and Persistence

### Data Volumes

| Volume           | Purpose        | Location  |
| ---------------- | -------------- | --------- |
| `p2p-data`       | Registry state | `/data`   |
| `gateway-data`   | Gateway state  | `/data`   |
| `compute-models` | AI models      | `/models` |

### Mount Models Directory

```yaml
compute-node:
  volumes:
    - ./local-models:/models:ro
```

### Backup Data

```bash
# Backup p2p data
docker run --rm -v ncn-network-v2-rs_p2p-data:/data -v $(pwd):/backup alpine \
  tar -czf /backup/p2p-data-backup.tar.gz /data

# Restore
docker run --rm -v ncn-network-v2-rs_p2p-data:/data -v $(pwd):/backup alpine \
  tar -xzf /backup/p2p-data-backup.tar.gz -C /
```

***

## Networking

### Default Network

Docker Compose creates a bridge network:

* Subnet: `172.20.0.0/16`
* Services communicate via service names

### Port Mapping

| Service           | Internal | External |
| ----------------- | -------- | -------- |
| P2P Registry gRPC | 50050    | 50050    |
| P2P Registry P2P  | 8828     | 8828     |
| Gateway gRPC      | 50051    | 50051    |
| Gateway HTTP      | 8080     | 8080     |
| Gateway WebSocket | 9000     | 9000     |

### Custom Network

```yaml
networks:
  ncn-network:
    driver: bridge
    ipam:
      config:
        - subnet: 10.10.0.0/16
```

***

## Health Checks

### Built-in Health Checks

```yaml
healthcheck:
  test: ["CMD", "nc", "-z", "localhost", "50050"]
  interval: 10s
  timeout: 5s
  retries: 5
  start_period: 15s
```

### Manual Health Check

```bash
# Check gateway health
curl http://localhost:8080/health

# Check container status
docker inspect --format='{{.State.Health.Status}}' ncn-gateway
```

***

## Logging

### View Logs

```bash
# All services
docker compose logs -f

# Specific service
docker compose logs -f gateway

# Last N lines
docker compose logs --tail=100 gateway
```

### Log Configuration

```yaml
gateway:
  logging:
    driver: "json-file"
    options:
      max-size: "100m"
      max-file: "3"
```

### Ship Logs to External Service

```yaml
gateway:
  logging:
    driver: "fluentd"
    options:
      fluentd-address: "localhost:24224"
```

***

## Resource Limits

### Set Resource Constraints

```yaml
compute-node:
  deploy:
    resources:
      limits:
        cpus: '2'
        memory: 4G
      reservations:
        cpus: '1'
        memory: 2G
```

***

## GPU Support

### Enable GPU Access

```yaml
compute-node:
  deploy:
    resources:
      reservations:
        devices:
          - driver: nvidia
            count: 1
            capabilities: [gpu]
```

### Verify GPU

```bash
docker exec ncn-compute-node nvidia-smi
```

***

## Monitoring

### Add Prometheus Metrics

```yaml
prometheus:
  image: prom/prometheus
  ports:
    - "9090:9090"
  volumes:
    - ./prometheus.yml:/etc/prometheus/prometheus.yml
```

### Prometheus Configuration

```yaml
# prometheus.yml
scrape_configs:
  - job_name: 'gateway'
    static_configs:
      - targets: ['gateway:8080']
```

***

## Troubleshooting

### Container Won't Start

```bash
# View container logs
docker compose logs gateway

# Check container status
docker compose ps -a

# Inspect container
docker inspect ncn-gateway
```

### Network Issues

```bash
# Test connectivity
docker exec ncn-gateway ping p2p-registry

# Check DNS resolution
docker exec ncn-gateway nslookup p2p-registry
```

### Permission Issues

```bash
# Fix volume permissions
sudo chown -R 1000:1000 ./data
```

***

## Production Checklist

* [ ] Use specific image tags, not `latest`
* [ ] Set resource limits
* [ ] Configure logging
* [ ] Enable health checks
* [ ] Use secrets management for private keys
* [ ] Set up monitoring
* [ ] Configure backup strategy
* [ ] Enable TLS for external access
* [ ] Review security settings

***

## Next Steps

* [Production Deployment](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/deployment/production.md) - Production considerations
* [Kubernetes Deployment](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/deployment/kubernetes.md) - K8s deployment
* [Monitoring Guide](https://github.com/NeuroChainAi/docs-guides/blob/main/guides/operators/monitoring.md) - Set up monitoring