Skip to content
HeliosDB HeliosDB Full

HeliosDB Docker Deployment Guide

HeliosDB Docker Deployment Guide

Complete guide for deploying HeliosDB using Docker and Docker Compose.

Table of Contents

  1. Prerequisites
  2. Quick Start
  3. Development Deployment
  4. Production Deployment
  5. Multi-Architecture Builds
  6. Configuration
  7. Monitoring
  8. Backup and Restore
  9. Troubleshooting

Prerequisites

  • Docker 20.10+ with Buildx support
  • Docker Compose 2.0+
  • 8GB+ RAM for development, 32GB+ for production
  • 100GB+ disk space per node

Quick Start

Single Container (Development)

Terminal window
# Build the image
docker build -f Dockerfile.prod -t heliosdb:latest .


# Run single container
docker run -d \
  --name heliosdb \
  -p 5432:5432 \
  -p 3306:3306 \
  -p 8443:8443 \
  -v heliosdb-data:/var/lib/heliosdb \
  heliosdb:latest


# Check health
docker logs -f heliosdb
curl http://localhost:8443/health

Development Cluster (3 nodes)

Terminal window
# Start development cluster
docker-compose up -d


# Check status
docker-compose ps


# View logs
docker-compose logs -f heliosdb-server


# Access services
psql -h localhost -p 5432 -U admin
mysql -h localhost -P 3306 -u admin
curl http://localhost:8443/health


# Stop cluster
docker-compose down


# Stop and remove volumes (data loss!)
docker-compose down -v

Production Deployment

5-Node High Availability Cluster

Terminal window
# Create data directories (optional, for bind mounts)
sudo mkdir -p /var/lib/heliosdb/{node1,node2,node3,node4,node5}
sudo chown -R 1000:1000 /var/lib/heliosdb


# Set environment variables
export GRAFANA_PASSWORD="secure_password_here"
export HELIOSDB_DATA_PATH="/var/lib/heliosdb"


# Start production cluster
docker-compose -f docker-compose.prod.yml up -d


# Check cluster health
docker-compose -f docker-compose.prod.yml ps


# View node logs
docker-compose -f docker-compose.prod.yml logs -f heliosdb-node1


# Check HAProxy stats
open http://localhost:8404/stats
# Default credentials: admin / heliosdb

Production Services

The production deployment includes:

  • 5 HeliosDB Nodes: High availability database cluster
  • HAProxy: Load balancer with health checks
  • Prometheus: Metrics collection and monitoring
  • Grafana: Visualization and dashboards
  • Jaeger: Distributed tracing
  • Node Exporter: System metrics
  • cAdvisor: Container metrics

Accessing Production Cluster

Terminal window
# Via HAProxy Load Balancer
psql -h localhost -p 5430 -U admin        # PostgreSQL (load balanced)
mysql -h localhost -P 3300 -u admin       # MySQL (load balanced)
curl http://localhost:8440/health         # HTTP (load balanced)


# Direct node access
psql -h localhost -p 5432 -U admin        # Node 1
psql -h localhost -p 5433 -U admin        # Node 2
psql -h localhost -p 5434 -U admin        # Node 3
psql -h localhost -p 5435 -U admin        # Node 4
psql -h localhost -p 5436 -U admin        # Node 5


# Monitoring interfaces
open http://localhost:3000                # Grafana (admin / heliosdb_prod)
open http://localhost:9090                # Prometheus
open http://localhost:16686               # Jaeger UI

Multi-Architecture Builds

Build for Multiple Architectures

Terminal window
# Build for AMD64 and ARM64
./scripts/build-docker.sh 4.0.0


# Build and push to registry
./scripts/build-docker.sh 4.0.0 true


# Custom registry
export DOCKER_REGISTRY="myregistry.com"
export DOCKER_REPOSITORY="myorg/heliosdb"
./scripts/build-docker.sh 4.0.0 true

Manual Multi-Arch Build

Terminal window
# Create builder
docker buildx create --name heliosdb-builder --use --bootstrap


# Build for multiple platforms
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --file Dockerfile.prod \
  --tag heliosdb/heliosdb:4.0.0 \
  --tag heliosdb/heliosdb:latest \
  --push \
  .

Configuration

Environment Variables

Server Configuration:

  • HELIOSDB_POSTGRES_PORT - PostgreSQL port (default: 5432)
  • HELIOSDB_MYSQL_PORT - MySQL port (default: 3306)
  • HELIOSDB_HTTP_PORT - HTTP Gateway port (default: 8443)
  • HELIOSDB_ORACLE_PORT - Oracle TNS port (default: 1521)
  • HELIOSDB_SQLSERVER_PORT - SQL Server TDS port (default: 1433)
  • HELIOSDB_BIND_ADDR - Bind address (default: 0.0.0.0)

Cluster Configuration:

  • HELIOS_NODE_TYPE - Node type (primary/replica)
  • HELIOS_NODE_ID - Unique node identifier
  • HELIOS_CLUSTER_NAME - Cluster name
  • HELIOS_RAFT_PEERS - Comma-separated Raft peer list
  • HELIOS_METADATA_NODES - Comma-separated metadata node list

Performance Tuning:

  • HELIOSDB_MAX_CONNECTIONS - Maximum connections (default: 1000)
  • HELIOSDB_SHARED_BUFFERS - Shared buffer size (default: 2GB)
  • HELIOSDB_EFFECTIVE_CACHE_SIZE - Cache size (default: 6GB)
  • HELIOSDB_WORK_MEM - Work memory (default: 64MB)

Logging:

  • RUST_LOG - Log level (info/debug/trace)
  • HELIOSDB_LOG_LEVEL - Application log level

Custom Configuration

Create a .env file:

.env
HELIOSDB_MAX_CONNECTIONS=2000
HELIOSDB_SHARED_BUFFERS=4GB
HELIOSDB_EFFECTIVE_CACHE_SIZE=12GB
RUST_LOG=debug
GRAFANA_PASSWORD=my_secure_password

Use with Docker Compose:

Terminal window
docker-compose --env-file .env -f docker-compose.prod.yml up -d

Monitoring

Prometheus Metrics

Access Prometheus: http://localhost:9090

Key metrics:

  • heliosdb_active_connections - Active database connections
  • heliosdb_query_latency_seconds - Query execution time
  • heliosdb_transactions_total - Total transactions
  • heliosdb_cache_hits_total - Cache hit rate
  • heliosdb_disk_reads_total - Disk read operations
  • heliosdb_raft_term - Raft consensus term

Grafana Dashboards

Access Grafana: http://localhost:3000

  • Username: admin
  • Password: heliosdb_prod (or custom from env)

Pre-configured dashboards:

  • HeliosDB Overview
  • Query Performance
  • Resource Usage
  • Replication Lag
  • Cache Performance
  • Error Rates

Jaeger Tracing

Access Jaeger: http://localhost:16686

View distributed traces for:

  • Query execution paths
  • Replication operations
  • Cross-node communication
  • API request flows

Backup and Restore

Manual Backup

Terminal window
# Backup using Docker exec
docker exec heliosdb-node1 /scripts/backup.sh


# Backup volumes
docker run --rm \
  -v heliosdb-node1-data:/data \
  -v $(pwd)/backups:/backup \
  alpine tar -czf /backup/node1-$(date +%Y%m%d).tar.gz -C /data .


# Copy backup from container
docker cp heliosdb-node1:/var/backups/heliosdb/. ./backups/

Automated Backups

Configure in docker-compose.prod.yml:

services:
  backup:
    image: heliosdb/heliosdb:4.0.0
    command: /scripts/backup.sh
    volumes:
      - node1-data:/var/lib/heliosdb:ro
      - ./backups:/var/backups/heliosdb
    environment:
      - BACKUP_SCHEDULE=0 2 * * *  # Daily at 2 AM
      - BACKUP_RETENTION=7

Restore from Backup

Terminal window
# Stop the cluster
docker-compose -f docker-compose.prod.yml down


# Restore volume
docker run --rm \
  -v heliosdb-node1-data:/data \
  -v $(pwd)/backups:/backup \
  alpine sh -c "rm -rf /data/* && tar -xzf /backup/node1-20250102.tar.gz -C /data"


# Restart cluster
docker-compose -f docker-compose.prod.yml up -d

Troubleshooting

Check Container Health

Terminal window
# Check running containers
docker-compose -f docker-compose.prod.yml ps


# Check container logs
docker-compose -f docker-compose.prod.yml logs -f heliosdb-node1


# Check resource usage
docker stats


# Inspect container
docker inspect heliosdb-node1

Common Issues

Container won’t start:

Terminal window
# Check logs
docker logs heliosdb-node1


# Check permissions
docker exec heliosdb-node1 ls -la /var/lib/heliosdb


# Check disk space
docker exec heliosdb-node1 df -h

Connection refused:

Terminal window
# Check if ports are bound
netstat -tulpn | grep -E '5432|3306|8443'


# Test connectivity
docker exec heliosdb-node1 nc -zv localhost 5432


# Check firewall rules
sudo ufw status

Poor performance:

Terminal window
# Check resource limits
docker inspect heliosdb-node1 | grep -A 10 Resources


# Monitor metrics
curl http://localhost:9090/metrics


# Check disk I/O
docker stats --no-stream

Cluster split-brain:

Terminal window
# Check Raft status
docker exec heliosdb-node1 heliosdb-cli cluster status


# Check logs for election issues
docker-compose logs | grep -i raft


# Force re-election
docker-compose restart heliosdb-node1

Health Checks

Terminal window
# PostgreSQL health
psql -h localhost -p 5432 -U admin -c "SELECT 1;"


# MySQL health
mysql -h localhost -P 3306 -u admin -e "SELECT 1;"


# HTTP health endpoint
curl http://localhost:8443/health
curl http://localhost:8443/metrics


# HAProxy health
curl http://localhost:8404/stats

Performance Tuning

Terminal window
# Increase resources
docker-compose -f docker-compose.prod.yml up -d --scale heliosdb-node=7


# Adjust memory limits
docker update --memory 16g --memory-swap 32g heliosdb-node1


# Monitor query performance
docker exec heliosdb-node1 heliosdb-cli query stats

Production Checklist

  • Review and customize environment variables
  • Set strong passwords and secrets
  • Configure persistent storage paths
  • Set up backup automation
  • Configure monitoring alerts
  • Review resource limits (CPU, memory)
  • Enable SSL/TLS for external access
  • Set up log aggregation
  • Configure firewall rules
  • Test disaster recovery procedures
  • Document access credentials
  • Set up monitoring dashboards

Support