metabuilder/dbal/cpp/docs/README.Docker.md

DBAL Daemon Docker Deployment Guide

Quick Start

Build the Docker Image

cd dbal/cpp
docker build -t dbal-daemon:latest .

Note: The Dockerfile uses Conan to fetch build dependencies (including Drogon). Ensure the build environment has network access.

Run with Docker

# Basic run
docker run -p 8080:8080 dbal-daemon:latest

# With environment variables
docker run -p 8080:8080 \
  -e DBAL_LOG_LEVEL=debug \
  -e DBAL_MODE=development \
  dbal-daemon:latest

# With custom config
docker run -p 8080:8080 \
  -v $(pwd)/config.yaml:/app/config.yaml:ro \
  dbal-daemon:latest

Run with Docker Compose

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f dbal

# Stop services
docker-compose down

Environment Variables

The daemon supports the following environment variables:

Variable	Default	Description
DBAL_BIND_ADDRESS	0.0.0.0	Bind address (use 0.0.0.0 in Docker)
DBAL_PORT	8080	Port number
DBAL_LOG_LEVEL	info	Log level (trace/debug/info/warn/error/critical)
DBAL_MODE	production	Run mode (production/development)
DBAL_CONFIG	/app/config.yaml	Configuration file path
DBAL_DAEMON	true	Run in daemon mode (Docker default)

Production Deployment

Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: dbal-daemon
spec:
  replicas: 3
  selector:
    matchLabels:
      app: dbal
  template:
    metadata:
      labels:
        app: dbal
    spec:
      containers:
      - name: dbal
        image: dbal-daemon:latest
        ports:
        - containerPort: 8080
        env:
        - name: DBAL_BIND_ADDRESS
          value: "0.0.0.0"
        - name: DBAL_LOG_LEVEL
          value: "info"
        resources:
          limits:
            cpu: "1"
            memory: "512Mi"
          requests:
            cpu: "100m"
            memory: "128Mi"
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 10
          periodSeconds: 30
        readinessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 10
---
apiVersion: v1
kind: Service
metadata:
  name: dbal-service
spec:
  selector:
    app: dbal
  ports:
  - protocol: TCP
    port: 80
    targetPort: 8080
  type: LoadBalancer

Docker Swarm Deployment

# Create overlay network
docker network create --driver overlay dbal-network

# Deploy stack
docker stack deploy -c docker-compose.yml dbal

# Scale service
docker service scale dbal_dbal=5

# View services
docker stack services dbal

Multi-Stage Build

The Dockerfile uses multi-stage builds for:

• Smaller image size: Runtime image ~50MB vs build ~500MB
• Security: Only runtime dependencies in final image
• Speed: Build cache optimization

Security Best Practices

1. Non-root user: Daemon runs as user dbal (UID 1000)
2. Minimal base: Ubuntu 22.04 with only required packages
3. Read-only config: Mount config.yaml as read-only
4. Network isolation: Use Docker networks
5. Resource limits: Set CPU and memory limits

Health Checks

The container includes a health check that:

• Checks /health endpoint every 30 seconds
• Waits 5 seconds before first check
• Marks unhealthy after 3 failed attempts

Logging

View logs:

# Docker
docker logs -f <container_id>

# Docker Compose
docker-compose logs -f dbal

# Kubernetes
kubectl logs -f deployment/dbal-daemon

# With log level
docker run -e DBAL_LOG_LEVEL=debug dbal-daemon:latest

Volumes

Mount persistent data:

docker run -p 8080:8080 \
  -v /path/to/config.yaml:/app/config.yaml:ro \
  -v /path/to/data:/app/data \
  dbal-daemon:latest

Behind Nginx Reverse Proxy

The daemon is designed to run behind nginx for:

• SSL/TLS termination
• Load balancing
• Rate limiting
• Caching

See NGINX_INTEGRATION.md for nginx configuration examples.

Troubleshooting

Container won't start

# Check logs
docker logs <container_id>

# Run interactively
docker run -it --entrypoint /bin/bash dbal-daemon:latest

# Check health
docker inspect --format='{{.State.Health.Status}}' <container_id>

Port already in use

# Use different port
docker run -p 8081:8080 dbal-daemon:latest

# Or set via environment
docker run -p 8081:8081 -e DBAL_PORT=8081 dbal-daemon:latest

Permission denied

# Check file ownership
ls -la /path/to/config.yaml

# Fix ownership (config should be readable by UID 1000)
chown 1000:1000 /path/to/config.yaml

Building for Multiple Platforms

# Enable buildx
docker buildx create --use

# Build for multiple platforms
docker buildx build \
  --platform linux/amd64,linux/arm64,linux/arm/v7 \
  -t dbal-daemon:latest \
  --push .

Development

For development, use interactive mode:

docker run -it \
  -e DBAL_DAEMON=false \
  -e DBAL_LOG_LEVEL=debug \
  --entrypoint ./dbal_daemon \
  dbal-daemon:latest

This gives you the interactive command prompt for debugging.