---
title: "Docker Compose Guide"
---

# Docker Compose Guide

Complete guide to using Docker Compose for HeliosDB deployments.

## Overview

Docker Compose files are organized by environment:
- **Development** - For local development and testing
- **Production** - For production deployments
- **Examples** - Sample configurations and integrations

## File Locations

All compose files are in `deployment/docker/compose/`

### Development

| File | Purpose |
|------|---------|
| `development/docker-compose.yml` | Full development cluster |
| `development/docker-compose.simple.yml` | Single-node simple setup |

### Production

| File | Purpose |
|------|---------|
| `production/docker-compose.yml` | Production HA cluster |

### Examples

| File | Purpose |
|------|---------|
| `examples/docker-compose.example.yml` | Client integration example |
| `examples/docker-compose.lite.yml` | HeliosDB Lite standalone |

## Development Deployment

### Simple Single-Node (Quick Start)

**File:** `development/docker-compose.simple.yml`

**Use this for:**
- Quick testing
- Feature development
- Minimal resource usage
- Single developer workflow

**Start:**
```bash
cd deployment/docker/compose/development
docker-compose -f docker-compose.simple.yml up
```

**Services:**
- HeliosDB single node (all-in-one)
- Basic monitoring

**Ports:**
- PostgreSQL: 5432
- MongoDB: 27017
- HTTP API: 8080

---

### Full Development Cluster

**File:** `development/docker-compose.yml`

**Use this for:**
- Distributed features testing
- Multi-node behavior
- Performance testing
- Integration testing

**Start:**
```bash
cd deployment/docker/compose/development
docker-compose up
```

**Services:**
- Storage nodes (3 replicas)
- Compute nodes (2 replicas)
- Metadata nodes (3 replicas)
- Gateway/Router
- Prometheus
- Grafana
- HAProxy

**Ports:**
- PostgreSQL: 5432
- MongoDB: 27017
- HTTP API: 8080
- Grafana: 3000
- Prometheus: 9090

**Access:**
```bash
# PostgreSQL
psql -h localhost -p 5432 -U heliosdb

# MongoDB
mongosh mongodb://localhost:27017

# Grafana UI
open http://localhost:3000
# Default: admin/admin

# Prometheus
open http://localhost:9090
```

---

## Production Deployment

### High-Availability Cluster

**File:** `production/docker-compose.yml`

**Features:**
- Multi-node storage with replication
- Load balancing
- Health checks
- Resource limits
- Restart policies
- Logging configuration
- Volume management

**Prerequisites:**
```bash
# Create required directories
mkdir -p /var/lib/heliosdb/{storage,metadata,logs}

# Set permissions
chown -R 1000:1000 /var/lib/heliosdb
```

**Environment Configuration:**

Create `.env` file:
```bash
# .env
STORAGE_REPLICAS=3
COMPUTE_REPLICAS=2
POSTGRES_PASSWORD=changeme
MONGO_PASSWORD=changeme
ADMIN_PASSWORD=changeme
```

**Start:**
```bash
cd deployment/docker/compose/production
docker-compose up -d
```

**Verify:**
```bash
# Check all services are running
docker-compose ps

# Check logs
docker-compose logs -f

# Check health
docker-compose exec gateway curl -fsS http://127.0.0.1:8443/health
```

**Stop:**
```bash
docker-compose down

# With volume cleanup
docker-compose down -v
```

---

## Examples

### Client Integration Example

**File:** `examples/docker-compose.example.yml`

Shows how to integrate a client application with HeliosDB.

**Services:**
- HeliosDB cluster
- Example Node.js application
- Example Python application

**Usage:**
```bash
cd deployment/docker/compose/examples
docker-compose -f docker-compose.example.yml up
```

---

### HeliosDB Lite

**File:** `examples/docker-compose.lite.yml`

Minimal embedded database deployment.

**Use for:**
- Edge computing
- IoT devices
- Development testing
- Single-application database

**Usage:**
```bash
cd deployment/docker/compose/examples
docker-compose -f docker-compose.lite.yml up
```

---

## Configuration

### Environment Variables

Common environment variables across all compose files:

#### Database Configuration
```bash
HELIOSDB_PORT=5432              # PostgreSQL protocol port
HELIOSDB_MONGO_PORT=27017       # MongoDB protocol port
HELIOSDB_HTTP_PORT=8080         # HTTP API port
HELIOSDB_LOG_LEVEL=info         # Logging: debug, info, warn, error
```

#### Storage Configuration
```bash
HELIOSDB_STORAGE_PATH=/data     # Data directory
HELIOSDB_WAL_PATH=/wal          # Write-ahead log directory
HELIOSDB_CACHE_SIZE=512MB       # Cache size
HELIOSDB_MAX_CONNECTIONS=100    # Max client connections
```

#### Replication Configuration
```bash
HELIOSDB_REPLICATION_FACTOR=3   # Data replication factor
HELIOSDB_CONSISTENCY=quorum     # Consistency level
```

### Volume Management

#### Development Volumes
```yaml
volumes:
  heliosdb-data:          # Main data volume
  heliosdb-metadata:      # Metadata volume
  heliosdb-logs:          # Logs volume
```

#### Production Volumes
```bash
# Use bind mounts for production
volumes:
  - /var/lib/heliosdb/storage:/data
  - /var/lib/heliosdb/metadata:/metadata
  - /var/log/heliosdb:/logs
```

### Network Configuration

All compose files use bridge networks:

```yaml
networks:
  heliosdb-network:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/16
```

### Resource Limits

Production compose file includes resource limits:

```yaml
services:
  storage:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G
        reservations:
          cpus: '1'
          memory: 2G
```

## Scaling

### Horizontal Scaling

```bash
# Scale storage nodes
docker-compose up -d --scale storage=5

# Scale compute nodes
docker-compose up -d --scale compute=4
```

### Vertical Scaling

Edit resource limits in compose file:

```yaml
services:
  storage:
    deploy:
      resources:
        limits:
          cpus: '4'      # Increase CPU
          memory: 8G     # Increase RAM
```

## Monitoring

### Grafana Dashboards

Access: `http://localhost:3000`

**Default credentials:** admin/admin

**Available dashboards:**
- Cluster Overview
- Storage Performance
- Query Performance
- Resource Utilization

### Prometheus Metrics

Access: `http://localhost:9090`

**Useful queries:**
```promql
# Query rate
rate(heliosdb_queries_total[5m])

# Storage usage
heliosdb_storage_bytes_used

# Connection count
heliosdb_connections_active
```

### Logs

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

# Specific service
docker-compose logs -f storage

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

## Troubleshooting

### Services Won't Start

**Check logs:**
```bash
docker-compose logs <service-name>
```

**Common issues:**
- Port already in use
- Insufficient resources
- Volume permissions

### Connection Refused

**Check service health:**
```bash
docker-compose ps
docker-compose exec <service> curl -fsS http://127.0.0.1:8443/health
```

### Performance Issues

**Check resource usage:**
```bash
docker stats
```

**Increase resources:**
```yaml
deploy:
  resources:
    limits:
      cpus: '4'
      memory: 8G
```

### Data Persistence

**Verify volumes:**
```bash
docker volume ls
docker volume inspect <volume-name>
```

**Backup volumes:**
```bash
docker run --rm \
  -v <volume-name>:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/backup.tar.gz /data
```

## Best Practices

### Development

1. Use named volumes for data persistence
2. Enable debug logging for troubleshooting
3. Use simple config for quick iteration
4. Mount code for hot-reload when applicable

### Production

1. Use bind mounts for production data
2. Set resource limits for all services
3. Enable health checks
4. Configure restart policies
5. Use secrets for sensitive data
6. Enable logging drivers
7. Regular backups
8. Monitor resource usage

### Security

```yaml
# Use secrets
secrets:
  db_password:
    file: ./secrets/db_password.txt

services:
  storage:
    secrets:
      - db_password
```

## Advanced Configurations

### Custom Network

```yaml
networks:
  heliosdb-backend:
    driver: bridge
    internal: true
  heliosdb-frontend:
    driver: bridge
```

### Health Checks

```yaml
services:
  storage:
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://127.0.0.1:8443/health"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 30s
```

### Logging

```yaml
services:
  storage:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
```

## Migration

### From Simple to Full Development

1. Stop simple deployment
2. Backup data
3. Start full development cluster
4. Restore data

### From Development to Production

See: Migration Guide

---

**Next:** Kubernetes Guide