Docker Images Guide

This guide explains each Dockerfile and how to use them for building HeliosDB images.

Available Dockerfiles

All Dockerfiles are located in deployment/docker/images/

1. Dockerfile (Standard Development)

Location: deployment/docker/images/Dockerfile

Purpose: Standard multi-stage build for development and testing

Features:

Multi-stage build (builder + runtime)
Full Rust toolchain in builder stage
Minimal runtime image based on Debian slim
Includes all HeliosDB components
Development tools included

Build:

docker build -t heliosdb:dev -f deployment/docker/images/Dockerfile .

Run:

docker run -p 5432:5432 -p 27017:27017 heliosdb:dev

Use Cases:

Local development
Integration testing
Feature development
Debugging

2. Dockerfile.production (Optimized Production)

Location: deployment/docker/images/Dockerfile.production

Purpose: Production-optimized build with security and performance focus

Features:

Multi-stage build with optimization
Minimal attack surface
Security hardening
Health checks included
Non-root user
Release build profile

Build:

docker build -t heliosdb:latest -f deployment/docker/images/Dockerfile.production .

Run:

docker run -d \
  --name heliosdb-prod \
  -p 5432:5432 \
  -p 27017:27017 \
  -v heliosdb-data:/var/lib/heliosdb \
  heliosdb:latest

Use Cases:

Production deployments
Cloud environments
Container orchestration (K8s, ECS)
CI/CD pipelines

Environment Variables:

HELIOSDB_PORT - Main port (default: 5432)
HELIOSDB_MONGO_PORT - MongoDB protocol port (default: 27017)
HELIOSDB_LOG_LEVEL - Logging level (default: info)

3. Dockerfile.prebuilt (Prebuilt Binaries)

Location: deployment/docker/images/Dockerfile.prebuilt

Purpose: Uses prebuilt binaries for faster image creation

Features:

No compilation required
Fast build times
Smaller build context
Uses official releases

Build:

# Assumes binaries are in ./target/release/
docker build -t heliosdb:prebuilt -f deployment/docker/images/Dockerfile.prebuilt .

Prerequisites:

# Build binaries first
cargo build --release

Run:

docker run -p 5432:5432 heliosdb:prebuilt

Use Cases:

Quick testing
Binary distribution
CI/CD with pre-built artifacts
Deployment verification

4. Dockerfile.lite (HeliosDB Lite)

Location: deployment/docker/images/Dockerfile.lite

Purpose: Lightweight embedded database version

Features:

Single binary
Minimal dependencies
Embedded mode
Quick startup
Small image size (~50MB)

Build:

docker build -t heliosdb:lite -f deployment/docker/images/Dockerfile.lite ./heliosdb-lite

Run:

# Standalone mode
docker run -p 3306:3306 heliosdb:lite

# With persistent storage
docker run -v heliosdb-lite:/data -p 3306:3306 heliosdb:lite

Use Cases:

Edge computing
IoT devices
Embedded systems
Testing and development
Single-node deployments

Build Optimization

Multi-Stage Build Benefits

All Dockerfiles use multi-stage builds to:

Separate build and runtime environments
Reduce final image size
Improve security by removing build tools
Cache dependencies efficiently

Build Cache

To maximize Docker build cache:

# Use BuildKit for better caching
DOCKER_BUILDKIT=1 docker build -t heliosdb:dev -f deployment/docker/images/Dockerfile .

Build Arguments

Common build arguments:

docker build \
  --build-arg RUST_VERSION=1.75 \
  --build-arg BUILD_PROFILE=release \
  -t heliosdb:custom \
  -f deployment/docker/images/Dockerfile .

Image Tagging Strategy

Development

docker build -t heliosdb:dev -f deployment/docker/images/Dockerfile .
docker tag heliosdb:dev heliosdb:dev-$(git rev-parse --short HEAD)

Production

docker build -t heliosdb:v7.0 -f deployment/docker/images/Dockerfile.production .
docker tag heliosdb:v7.0 heliosdb:latest
docker tag heliosdb:v7.0 heliosdb:stable

Lite Version

docker build -t heliosdb:lite-v7.0 -f deployment/docker/images/Dockerfile.lite ./heliosdb-lite
docker tag heliosdb:lite-v7.0 heliosdb:lite

Registry Publishing

Docker Hub

docker tag heliosdb:latest heliosdb/heliosdb:v7.0
docker push heliosdb/heliosdb:v7.0

Private Registry

docker tag heliosdb:latest registry.example.com/heliosdb:v7.0
docker push registry.example.com/heliosdb:v7.0

Security Scanning

Scan images for vulnerabilities:

# Using Docker Scout
docker scout cves heliosdb:latest

# Using Trivy
trivy image heliosdb:latest

# Using Snyk
snyk container test heliosdb:latest

Resource Requirements

Image	Build Time	Image Size	RAM	CPU
Dockerfile	~10 min	800MB	2GB	2 cores
Dockerfile.production	~12 min	600MB	1GB	2 cores
Dockerfile.prebuilt	~1 min	700MB	1GB	1 core
Dockerfile.lite	~5 min	50MB	256MB	1 core

Troubleshooting

Build Failures

Issue: Out of memory during build

# Increase Docker memory limit
docker build --memory 4g -t heliosdb:dev -f deployment/docker/images/Dockerfile .

Issue: Dependency cache invalidation

# Use BuildKit mount caches
DOCKER_BUILDKIT=1 docker build \
  --build-arg BUILDKIT_INLINE_CACHE=1 \
  -t heliosdb:dev \
  -f deployment/docker/images/Dockerfile .

Issue: Network timeouts

# Add timeouts and retries
docker build \
  --network host \
  --build-arg CARGO_NET_RETRY=3 \
  -t heliosdb:dev \
  -f deployment/docker/images/Dockerfile .

Runtime Issues

Issue: Container exits immediately

# Check logs
docker logs <container-id>

# Run with interactive shell
docker run -it heliosdb:dev /bin/bash

Issue: Permission denied

# Run with correct user
docker run --user $(id -u):$(id -g) heliosdb:dev

Best Practices

Always use multi-stage builds for smaller images
Pin base image versions to ensure reproducibility
Scan images regularly for security vulnerabilities
Use .dockerignore to exclude unnecessary files
Set resource limits in production
Use health checks for container orchestration
Run as non-root user for security
Keep images minimal by removing build tools

Example .dockerignore

target/
.git/
.github/
docs/
tests/
benches/
*.md
Dockerfile*
docker-compose*

Next: Docker Compose Guide