Docker Deployment Guide

Docker Deployment Guide

This guide covers building, running, and deploying HeliosDB and HeliosProxy using Docker containers.

Quick Start

Pull Pre-built Images

# HeliosDB-Lite (database server)
docker pull ghcr.io/heliosdb/heliosdb-lite:latest

# HeliosProxy (connection pooler)
docker pull ghcr.io/heliosdb/heliosproxy:latest

Run HeliosDB

# Simple single-node deployment
docker run -d \
  --name heliosdb \
  -p 5432:5432 \
  -p 8080:8080 \
  -v heliosdb_data:/data \
  ghcr.io/heliosdb/heliosdb-lite:latest

Run HeliosProxy

# Connection pooler (requires HeliosDB backend)
docker run -d \
  --name heliosproxy \
  -p 6432:6432 \
  -p 9090:9090 \
  -e HELIOS_PROXY_PRIMARY=heliosdb:5432 \
  --link heliosdb \
  ghcr.io/heliosdb/heliosproxy:latest

Building Images Locally

Using Build Script

# Build all images
./scripts/docker-build.sh

# Build specific image
./scripts/docker-build.sh heliosdb
./scripts/docker-build.sh proxy

# Build with version tag
./scripts/docker-build.sh -v 1.0.0 all

# Build and push to registry
./scripts/docker-build.sh -p all

# Multi-architecture build
./scripts/docker-build.sh -m -p all

Manual Build

# HeliosDB-Lite
docker build -t heliosdb-lite:local -f deployment/docker/Dockerfile .

# HeliosProxy
docker build -t heliosproxy:local -f demos/docker/Dockerfile.proxy .

Docker Compose Deployments

Single Node

docker-compose.yml

version: '3.8'

services:
  heliosdb:
    image: ghcr.io/heliosdb/heliosdb-lite:latest
    ports:
      - "5432:5432"
      - "8080:8080"
    volumes:
      - heliosdb_data:/data
    environment:
      - HELIOSDB_LOG_LEVEL=info

volumes:
  heliosdb_data:

With HeliosProxy

version: '3.8'

services:
  heliosdb:
    image: ghcr.io/heliosdb/heliosdb-lite:latest
    ports:
      - "5432:5432"
    volumes:
      - heliosdb_data:/data

  proxy:
    image: ghcr.io/heliosdb/heliosproxy:latest
    ports:
      - "6432:6432"   # Client connections
      - "9090:9090"   # Admin/metrics
    environment:
      - HELIOS_PROXY_PRIMARY=heliosdb:5432
      - HELIOS_PROXY_POOL_MODE=transaction
    depends_on:
      - heliosdb

volumes:
  heliosdb_data:

HA Cluster with Proxy

version: '3.8'

services:
  helios-primary:
    image: ghcr.io/heliosdb/heliosdb-lite:latest
    environment:
      - HELIOSDB_ROLE=primary
      - HELIOSDB_CLUSTER_ID=demo-cluster
    volumes:
      - primary_data:/data

  helios-standby1:
    image: ghcr.io/heliosdb/heliosdb-lite:latest
    environment:
      - HELIOSDB_ROLE=standby
      - HELIOSDB_PRIMARY=helios-primary:5433
    volumes:
      - standby1_data:/data
    depends_on:
      - helios-primary

  helios-standby2:
    image: ghcr.io/heliosdb/heliosdb-lite:latest
    environment:
      - HELIOSDB_ROLE=standby
      - HELIOSDB_PRIMARY=helios-primary:5433
    volumes:
      - standby2_data:/data
    depends_on:
      - helios-primary

  proxy:
    image: ghcr.io/heliosdb/heliosproxy:latest
    ports:
      - "6432:6432"
      - "9090:9090"
    environment:
      - HELIOS_PROXY_PRIMARY=helios-primary:5432
      - HELIOS_PROXY_STANDBYS=helios-standby1:5432,helios-standby2:5432
      - HELIOS_PROXY_POOL_MODE=transaction
    depends_on:
      - helios-primary
      - helios-standby1
      - helios-standby2

volumes:
  primary_data:
  standby1_data:
  standby2_data:

Image Configuration

HeliosDB-Lite

Environment Variable	Default	Description
HELIOSDB_DATA_DIR	/data	Data storage directory
HELIOSDB_LOG_LEVEL	info	Log level (trace, debug, info, warn, error)
HELIOSDB_MODE	server	Operating mode
HELIOSDB_REST_PORT	8080	REST API port
HELIOSDB_PG_PORT	5432	PostgreSQL protocol port
HELIOSDB_ENCRYPTION_KEY	-	Encryption key (hex)
HELIOSDB_API_KEY	-	API authentication key
HELIOSDB_MAX_CONNECTIONS	100	Maximum client connections
HELIOSDB_CACHE_SIZE_MB	512	Query cache size

HeliosProxy

Environment Variable	Default	Description
HELIOS_PROXY_LISTEN	0.0.0.0:6432	Client listen address
HELIOS_PROXY_ADMIN	0.0.0.0:9090	Admin API address
HELIOS_PROXY_PRIMARY	-	Primary backend address
HELIOS_PROXY_STANDBYS	-	Standby addresses (comma-separated)
HELIOS_PROXY_POOL_MODE	transaction	Pool mode (session/transaction/statement)
HELIOS_PROXY_CACHE_ENABLED	true	Enable query caching

Volumes and Persistence

Data Volume

# Create named volume
docker volume create heliosdb_data

# Run with volume
docker run -v heliosdb_data:/data ghcr.io/heliosdb/heliosdb-lite:latest

# Backup volume
docker run --rm -v heliosdb_data:/data -v $(pwd):/backup alpine \
  tar czf /backup/heliosdb_backup.tar.gz /data

Host Directory

# Mount host directory
docker run -v /path/to/data:/data ghcr.io/heliosdb/heliosdb-lite:latest

Health Checks

Both images include built-in health checks:

# Check HeliosDB health
curl http://localhost:8080/health

# Check HeliosProxy health
curl http://localhost:9090/health

# Docker health status
docker inspect --format='{{.State.Health.Status}}' heliosdb

Resource Limits

services:
  heliosdb:
    image: ghcr.io/heliosdb/heliosdb-lite:latest
    deploy:
      resources:
        limits:
          cpus: '4'
          memory: 8G
        reservations:
          cpus: '1'
          memory: 2G

Networking

Bridge Network (default)

# Create network
docker network create helios-net

# Run containers on network
docker run --network helios-net --name heliosdb ...
docker run --network helios-net --name proxy ...

Host Network (for performance)

docker run --network host ghcr.io/heliosdb/heliosdb-lite:latest

Security Considerations

Non-root User

Both images run as non-root user helios (UID 1000).

Read-only Root Filesystem

docker run --read-only \
  -v heliosdb_data:/data \
  -v heliosdb_tmp:/tmp \
  ghcr.io/heliosdb/heliosdb-lite:latest

Secrets

# Using Docker secrets
echo "my-secret-key" | docker secret create heliosdb_api_key -

docker service create \
  --secret heliosdb_api_key \
  -e HELIOSDB_API_KEY_FILE=/run/secrets/heliosdb_api_key \
  ghcr.io/heliosdb/heliosdb-lite:latest

Troubleshooting

View Logs

docker logs heliosdb
docker logs -f heliosdb  # Follow logs

Shell Access

# Note: Images use slim base, shell is /bin/sh
docker exec -it heliosdb /bin/sh

Check Configuration

docker exec heliosdb cat /etc/helios/heliosdb.toml

Common Issues

Container exits immediately

• Check logs: docker logs heliosdb
• Verify data directory permissions
• Check port conflicts

Cannot connect

• Verify port mapping: docker port heliosdb
• Check firewall rules
• Ensure health check passes

Performance issues

• Increase memory limits
• Use host networking
• Check I/O performance of volume mount

CI/CD Integration

GitHub Actions

Images are automatically built on:

• Push to main or heliosproxy branches
• Git tags (v*)
• Pull requests (build only, no push)

See .github/workflows/docker-publish.yml for workflow details.

Manual Registry Push

# Login to registry
docker login ghcr.io

# Tag and push
docker tag heliosdb-lite:local ghcr.io/myorg/heliosdb-lite:1.0.0
docker push ghcr.io/myorg/heliosdb-lite:1.0.0