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:

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:

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:

# 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:

# 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:

.env

HELIOSDB_VERSION=7.0
STORAGE_REPLICAS=3
COMPUTE_REPLICAS=2
POSTGRES_PASSWORD=changeme
MONGO_PASSWORD=changeme
ADMIN_PASSWORD=changeme

Start:

cd deployment/docker/compose/production
docker-compose up -d

Verify:

# Check all services are running
docker-compose ps

# Check logs
docker-compose logs -f

# Check health
docker-compose exec gateway heliosdb-cli health

Stop:

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:

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:

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

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

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

HELIOSDB_REPLICATION_FACTOR=3   # Data replication factor
HELIOSDB_CONSISTENCY=quorum     # Consistency level

Volume Management

Development Volumes

volumes:
  heliosdb-data:          # Main data volume
  heliosdb-metadata:      # Metadata volume
  heliosdb-logs:          # Logs volume

Production Volumes

# 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:

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

Resource Limits

Production compose file includes resource limits:

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

Scaling

Horizontal Scaling

# 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:

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:

# Query rate
rate(heliosdb_queries_total[5m])

# Storage usage
heliosdb_storage_bytes_used

# Connection count
heliosdb_connections_active

Logs

# 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:

docker-compose logs <service-name>

Common issues:

• Port already in use
• Insufficient resources
• Volume permissions

Connection Refused

Check service health:

docker-compose ps
docker-compose exec <service> heliosdb-cli ping

Performance Issues

Check resource usage:

docker stats

Increase resources:

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

Data Persistence

Verify volumes:

docker volume ls
docker volume inspect <volume-name>

Backup volumes:

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

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

services:
  storage:
    secrets:
      - db_password

Advanced Configurations

Custom Network

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

Health Checks

services:
  storage:
    healthcheck:
      test: ["CMD", "heliosdb-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 30s

Logging

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