Skip to content
HeliosDB Full

Production Deployment: Docker Deployment

Production Deployment: Docker Deployment

Part of: Production Deployment Guide

4.1 Docker Compose Setup

docker-compose.yml:

version: '3.8'


services:
  # Metadata nodes (Raft cluster)
  metadata-1:
    image: heliosdb/heliosdb:6.0.0
    container_name: heliosdb-metadata-1
    command: >
      /usr/local/bin/heliosdb-metadata
      --node-id=metadata-1
      --listen-addr=0.0.0.0:7001
      --raft-addr=0.0.0.0:8300
      --data-dir=/data/metadata
      --cluster-peers=metadata-1:8300,metadata-2:8300,metadata-3:8300
    environment:
      - RUST_LOG=info,heliosdb=debug
      - RUST_BACKTRACE=1
    volumes:
      - metadata-1-data:/data
      - ./config:/etc/heliosdb:ro
    ports:
      - "7001:7001"
      - "8300:8300"
      - "9091:9090"
    networks:
      - heliosdb
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9090/health"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 30s


  metadata-2:
    image: heliosdb/heliosdb:6.0.0
    container_name: heliosdb-metadata-2
    command: >
      /usr/local/bin/heliosdb-metadata
      --node-id=metadata-2
      --listen-addr=0.0.0.0:7001
      --raft-addr=0.0.0.0:8300
      --data-dir=/data/metadata
      --cluster-peers=metadata-1:8300,metadata-2:8300,metadata-3:8300
    environment:
      - RUST_LOG=info,heliosdb=debug
    volumes:
      - metadata-2-data:/data
      - ./config:/etc/heliosdb:ro
    ports:
      - "7011:7001"
      - "8301:8300"
      - "9092:9090"
    networks:
      - heliosdb
    restart: unless-stopped
    depends_on:
      - metadata-1


  metadata-3:
    image: heliosdb/heliosdb:6.0.0
    container_name: heliosdb-metadata-3
    command: >
      /usr/local/bin/heliosdb-metadata
      --node-id=metadata-3
      --listen-addr=0.0.0.0:7001
      --raft-addr=0.0.0.0:8300
      --data-dir=/data/metadata
      --cluster-peers=metadata-1:8300,metadata-2:8300,metadata-3:8300
    environment:
      - RUST_LOG=info,heliosdb=debug
    volumes:
      - metadata-3-data:/data
      - ./config:/etc/heliosdb:ro
    ports:
      - "7012:7001"
      - "8302:8300"
      - "9093:9090"
    networks:
      - heliosdb
    restart: unless-stopped
    depends_on:
      - metadata-1


  # Storage nodes
  storage-1:
    image: heliosdb/heliosdb:6.0.0
    container_name: heliosdb-storage-1
    command: >
      /usr/local/bin/heliosdb-storage
      --node-id=storage-1
      --listen-addr=0.0.0.0:7002
      --data-dir=/data/storage
      --wal-dir=/wal
      --metadata-endpoints=metadata-1:7001,metadata-2:7001,metadata-3:7001
      --replication-factor=3
      --enable-compression=true
    environment:
      - RUST_LOG=info,heliosdb=debug
    volumes:
      - storage-1-data:/data
      - storage-1-wal:/wal
      - ./config:/etc/heliosdb:ro
    ports:
      - "7021:7002"
      - "9094:9090"
    networks:
      - heliosdb
    restart: unless-stopped
    depends_on:
      - metadata-1
      - metadata-2
      - metadata-3


  storage-2:
    image: heliosdb/heliosdb:6.0.0
    container_name: heliosdb-storage-2
    command: >
      /usr/local/bin/heliosdb-storage
      --node-id=storage-2
      --listen-addr=0.0.0.0:7002
      --data-dir=/data/storage
      --wal-dir=/wal
      --metadata-endpoints=metadata-1:7001,metadata-2:7001,metadata-3:7001
      --replication-factor=3
      --enable-compression=true
    environment:
      - RUST_LOG=info,heliosdb=debug
    volumes:
      - storage-2-data:/data
      - storage-2-wal:/wal
      - ./config:/etc/heliosdb:ro
    ports:
      - "7022:7002"
      - "9095:9090"
    networks:
      - heliosdb
    restart: unless-stopped
    depends_on:
      - metadata-1
      - metadata-2
      - metadata-3


  storage-3:
    image: heliosdb/heliosdb:6.0.0
    container_name: heliosdb-storage-3
    command: >
      /usr/local/bin/heliosdb-storage
      --node-id=storage-3
      --listen-addr=0.0.0.0:7002
      --data-dir=/data/storage
      --wal-dir=/wal
      --metadata-endpoints=metadata-1:7001,metadata-2:7001,metadata-3:7001
      --replication-factor=3
      --enable-compression=true
    environment:
      - RUST_LOG=info,heliosdb=debug
    volumes:
      - storage-3-data:/data
      - storage-3-wal:/wal
      - ./config:/etc/heliosdb:ro
    ports:
      - "7023:7002"
      - "9096:9090"
    networks:
      - heliosdb
    restart: unless-stopped
    depends_on:
      - metadata-1
      - metadata-2
      - metadata-3


  # Compute nodes
  compute-1:
    image: heliosdb/heliosdb:6.0.0
    container_name: heliosdb-compute-1
    command: >
      /usr/local/bin/heliosdb-compute
      --listen-addr=0.0.0.0:5432
      --graphql-addr=0.0.0.0:10000
      --metadata-endpoints=metadata-1:7001,metadata-2:7001,metadata-3:7001
      --storage-endpoints=storage-1:7002,storage-2:7002,storage-3:7002
      --max-connections=1000
      --enable-query-cache=true
      --enable-ai-optimization=true
    environment:
      - RUST_LOG=info,heliosdb=debug
    volumes:
      - ./config:/etc/heliosdb:ro
      - compute-1-cache:/cache
    ports:
      - "5432:5432"
      - "10000:10000"
      - "9097:9090"
    networks:
      - heliosdb
    restart: unless-stopped
    depends_on:
      - storage-1
      - storage-2
      - storage-3


  compute-2:
    image: heliosdb/heliosdb:6.0.0
    container_name: heliosdb-compute-2
    command: >
      /usr/local/bin/heliosdb-compute
      --listen-addr=0.0.0.0:5432
      --graphql-addr=0.0.0.0:10000
      --metadata-endpoints=metadata-1:7001,metadata-2:7001,metadata-3:7001
      --storage-endpoints=storage-1:7002,storage-2:7002,storage-3:7002
      --max-connections=1000
      --enable-query-cache=true
      --enable-ai-optimization=true
    environment:
      - RUST_LOG=info,heliosdb=debug
    volumes:
      - ./config:/etc/heliosdb:ro
      - compute-2-cache:/cache
    ports:
      - "5433:5432"
      - "10001:10000"
      - "9098:9090"
    networks:
      - heliosdb
    restart: unless-stopped
    depends_on:
      - storage-1
      - storage-2
      - storage-3


  # HAProxy load balancer
  haproxy:
    image: haproxy:2.8-alpine
    container_name: heliosdb-lb
    volumes:
      - ./haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro
    ports:
      - "5430:5432"
      - "8404:8404"  # Stats page
    networks:
      - heliosdb
    restart: unless-stopped
    depends_on:
      - compute-1
      - compute-2


  # Prometheus
  prometheus:
    image: prom/prometheus:v2.47.0
    container_name: heliosdb-prometheus
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--storage.tsdb.path=/prometheus'
      - '--storage.tsdb.retention.time=30d'
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prometheus-data:/prometheus
    ports:
      - "9090:9090"
    networks:
      - heliosdb
    restart: unless-stopped


  # Grafana
  grafana:
    image: grafana/grafana:10.1.0
    container_name: heliosdb-grafana
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
      - GF_INSTALL_PLUGINS=grafana-clock-panel,grafana-simple-json-datasource
    volumes:
      - grafana-data:/var/lib/grafana
      - ./grafana/dashboards:/etc/grafana/provisioning/dashboards:ro
      - ./grafana/datasources:/etc/grafana/provisioning/datasources:ro
    ports:
      - "3000:3000"
    networks:
      - heliosdb
    restart: unless-stopped
    depends_on:
      - prometheus


volumes:
  metadata-1-data:
  metadata-2-data:
  metadata-3-data:
  storage-1-data:
  storage-1-wal:
  storage-2-data:
  storage-2-wal:
  storage-3-data:
  storage-3-wal:
  compute-1-cache:
  compute-2-cache:
  prometheus-data:
  grafana-data:


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

4.2 Multi-Node Cluster

For production deployments across multiple physical/virtual machines, use Docker Swarm:

Initialize Swarm:

Terminal window
# On manager node
docker swarm init --advertise-addr <MANAGER-IP>


# On worker nodes
docker swarm join --token <TOKEN> <MANAGER-IP>:2377

docker-stack.yml:

version: '3.8'


services:
  metadata:
    image: heliosdb/heliosdb:6.0.0
    command: >
      /usr/local/bin/heliosdb-metadata
      --node-id={{.Task.Slot}}
      --listen-addr=0.0.0.0:7001
      --raft-addr=0.0.0.0:8300
      --data-dir=/data/metadata
    deploy:
      replicas: 3
      placement:
        constraints:
          - node.labels.role == metadata
        max_replicas_per_node: 1
      resources:
        limits:
          cpus: '4'
          memory: 8G
        reservations:
          cpus: '2'
          memory: 4G
      update_config:
        parallelism: 1
        delay: 30s
        order: stop-first
    volumes:
      - metadata-data:/data
    networks:
      - heliosdb
    ports:
      - "7001:7001"
      - "8300:8300"


  storage:
    image: heliosdb/heliosdb:6.0.0
    command: >
      /usr/local/bin/heliosdb-storage
      --node-id={{.Task.Slot}}
      --listen-addr=0.0.0.0:7002
      --data-dir=/data/storage
      --wal-dir=/wal
      --metadata-endpoints=metadata:7001
    deploy:
      replicas: 5
      placement:
        constraints:
          - node.labels.role == storage
        max_replicas_per_node: 1
      resources:
        limits:
          cpus: '8'
          memory: 32G
        reservations:
          cpus: '4'
          memory: 16G
    volumes:
      - storage-data:/data
      - storage-wal:/wal
    networks:
      - heliosdb
    ports:
      - "7002:7002"


  compute:
    image: heliosdb/heliosdb:6.0.0
    command: >
      /usr/local/bin/heliosdb-compute
      --listen-addr=0.0.0.0:5432
      --metadata-endpoints=metadata:7001
      --storage-endpoints=storage:7002
    deploy:
      replicas: 3
      placement:
        constraints:
          - node.labels.role == compute
      resources:
        limits:
          cpus: '8'
          memory: 16G
        reservations:
          cpus: '4'
          memory: 8G
    networks:
      - heliosdb
    ports:
      - "5432:5432"


volumes:
  metadata-data:
  storage-data:
  storage-wal:


networks:
  heliosdb:
    driver: overlay
    attachable: true

Deploy stack:

Terminal window
docker stack deploy -c docker-stack.yml heliosdb

4.3 Volume Management

Named Volumes (recommended for production):

Terminal window
# Create volumes
docker volume create --driver local \
  --opt type=none \
  --opt o=bind \
  --opt device=/mnt/data/metadata-1 \
  metadata-1-data


docker volume create --driver local \
  --opt type=none \
  --opt o=bind \
  --opt device=/mnt/data/storage-1 \
  storage-1-data

Volume Backup:

Terminal window
# Backup volume
docker run --rm \
  -v storage-1-data:/data \
  -v /backup:/backup \
  alpine tar czf /backup/storage-1-backup-$(date +%Y%m%d).tar.gz -C /data .


# Restore volume
docker run --rm \
  -v storage-1-data:/data \
  -v /backup:/backup \
  alpine tar xzf /backup/storage-1-backup-20251101.tar.gz -C /data

4.4 Network Configuration

Custom Bridge Network:

Terminal window
# Create custom network
docker network create \
  --driver bridge \
  --subnet 172.20.0.0/16 \
  --gateway 172.20.0.1 \
  --opt "com.docker.network.bridge.name"="heliosdb0" \
  --opt "com.docker.network.bridge.enable_icc"="true" \
  heliosdb-net

DNS Configuration:

# docker-compose.yml additions
services:
  metadata-1:
    dns:
      - 8.8.8.8
      - 8.8.4.4
    dns_search: heliosdb.local
    extra_hosts:
      - "metadata-1.heliosdb.local:172.20.0.10"
      - "storage-1.heliosdb.local:172.20.0.20"