Docker Deployment Guide
Note: The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
MDDB provides optimized Docker images based on Alpine Linux for minimal size and maximum security.
Table of Contents
- Quick Start
- Docker Images
- Production Deployment
- Development Setup
- Configuration
- Volumes and Persistence
- Networking
- Health Checks
- Security
- Troubleshooting
Quick Start
Using Docker Compose (Recommended)
make docker-up docker compose up -d
Access:
- HTTP API: http://localhost:11023
- gRPC API: localhost:11024
Using Docker CLI
make docker-build docker run -d \ --name mddb \ -p 11023:11023 \ -p 11024:11024 \ -v mddb-data:/app/data \ mddb:latest
Docker Images
Production Image
Base: Alpine Linux 3.23
Size: ~15 MB (compressed)
User: Non-root (uid: 1000)
Features:
- Multi-stage build for minimal size
- Static binary (no dependencies)
- Health checks included
- Security hardened
Build:
make docker-build
docker build -t mddb:latest -f services/mddbd/Dockerfile services/mddbd
Development Image
Base: golang:1.26-alpine
Size: ~500 MB
Features: Hot reload with Air
Build:
make docker-build-dev
docker build -t mddb:dev -f services/mddbd/Dockerfile.dev services/mddbd
Production Deployment
Docker Compose
File: docker-compose.yml
services: mddb: image: mddb:latest container_name: mddb-server restart: unless-stopped ports: - "11023:11023" # HTTP - "11024:11024" # gRPC volumes: - mddb-data:/app/data - ./backups:/app/backups environment: - MDDB_ADDR=:11023 - MDDB_GRPC_ADDR=:11024 - MDDB_MODE=wr - MDDB_PATH=/app/data/mddb.db - TZ=UTC networks: - mddb-network healthcheck: test: ["CMD", "wget", "--spider", "http://localhost:11023/v1/stats"] interval: 30s timeout: 3s retries: 3
Commands
make docker-up make docker-down make docker-logs make docker-shell make docker-clean
Development Setup
With Hot Reload
make docker-up-dev make docker-logs-dev
Features:
- Automatic rebuild on code changes
- Source code mounted as volume
- Air hot reload
- Go module cache persisted
Development Workflow
make docker-up-dev make docker-logs-dev make docker-down
Configuration
Environment Variables
| Variable | Default | Description |
|---|---|---|
MDDB_ADDR | :11023 | HTTP API address |
MDDB_GRPC_ADDR | :11024 | gRPC API address |
MDDB_MODE | wr | Access mode (read/write/wr) |
MDDB_PATH | /app/data/mddb.db | Database file path |
TZ | UTC | Timezone |
Custom Configuration
Create .env file:
MDDB_ADDR=:8080
MDDB_GRPC_ADDR=:8081
MDDB_MODE=read
TZ=Europe/Warsaw
Use with Docker Compose:
services: mddb: env_file: .env # ... rest of config
Volumes and Persistence
Named Volumes (Recommended)
volumes: mddb-data: driver: local name: mddb-data
Advantages:
- Managed by Docker
- Portable
- Easy backup
Commands:
docker volume ls docker volume inspect mddb-data docker run --rm \ -v mddb-data:/data \ -v $(pwd):/backup \ alpine tar czf /backup/mddb-backup.tar.gz -C /data . docker run --rm \ -v mddb-data:/data \ -v $(pwd):/backup \ alpine tar xzf /backup/mddb-backup.tar.gz -C /data
Bind Mounts
volumes: - ./data:/app/data - ./backups:/app/backups
Advantages:
- Direct file access
- Easy development
- Simple backup
Networking
Default Network
networks: mddb-network: driver: bridge name: mddb-network
Multiple Services
services: mddb: networks: - mddb-network app: networks: - mddb-network environment: - MDDB_HTTP_URL=http://mddb:11023 - MDDB_GRPC_URL=mddb:11024
External Network
make docker-setup-network networks: mddb-network: external: true name: mddb-network
Health Checks
Built-in Health Check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \ CMD wget --spider http://localhost:11023/v1/stats || exit 1
Check Status
docker ps docker inspect mddb-server | jq '.[0].State.Health'
Custom Health Check
healthcheck: test: ["CMD", "wget", "--spider", "http://localhost:11023/v1/stats"] interval: 10s timeout: 5s retries: 5 start_period: 10s
Security
Non-Root User
Container runs as user mddb (uid: 1000):
RUN addgroup -g 1000 mddb && \ adduser -D -u 1000 -G mddb mddb
USER mddb
Read-Only Filesystem
services: mddb: read_only: true tmpfs: - /tmp - /app/tmp volumes: - mddb-data:/app/data:rw
Resource Limits
services: mddb: deploy: resources: limits: cpus: '1.0' memory: 512M reservations: cpus: '0.5' memory: 256M
Security Options
services: mddb: security_opt: - no-new-privileges:true cap_drop: - ALL cap_add: - NET_BIND_SERVICE
Advanced Configuration
Behind Reverse Proxy
Nginx
upstream mddb_http { server localhost:11023;
} upstream mddb_grpc { server localhost:11024;
} server { listen 80; server_name api.example.com; location / { proxy_pass http://mddb_http; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; }
} server { listen 443 ssl http2; server_name grpc.example.com; location / { grpc_pass grpc://mddb_grpc; }
}
Traefik
services: mddb: labels: - "traefik.enable=true" - "traefik.http.routers.mddb.rule=Host(`api.example.com`)" - "traefik.http.services.mddb.loadbalancer.server.port=11023"
Multi-Container Setup
services: mddb-primary: image: mddb:latest environment: - MDDB_MODE=wr volumes: - mddb-primary:/app/data mddb-replica: image: mddb:latest environment: - MDDB_MODE=read volumes: - mddb-replica:/app/data
Troubleshooting
Container Won't Start
docker logs mddb-server docker inspect mddb-server | jq '.[0].State' docker run --rm -it mddb:latest sh
Permission Issues
docker run --rm \ -v mddb-data:/data \ alpine chown -R 1000:1000 /data
Database Corruption
make docker-down docker run --rm \ -v mddb-data:/data \ -v $(pwd):/backup \ alpine cp /data/mddb.db /backup/mddb.db.backup docker run --rm \ -v mddb-data:/data \ -v $(pwd):/backup \ alpine cp /backup/backup-xxx.db /data/mddb.db make docker-up
Performance Issues
docker stats mddb-server docker update --memory=1g --cpus=2 mddb-server
Network Issues
docker exec mddb-server wget -O- http://localhost:11023/v1/stats docker network inspect mddb-network docker network rm mddb-network
make docker-setup-network
Best Practices
Production Checklist
- ✅ Use named volumes for data persistence
- ✅ Set resource limits
- ✅ Enable health checks
- ✅ Run as non-root user
- ✅ Use read-only filesystem where possible
- ✅ Configure proper logging
- ✅ Set up monitoring
- ✅ Regular backups
- ✅ Use secrets for sensitive data
- ✅ Keep images updated
Backup Strategy
#!/bin/bash DATE=$(date +%Y-%m-%d)
BACKUP_DIR="/backups" docker exec mddb-server wget -O- \ "http://localhost:11023/v1/backup?to=backup-${DATE}.db" docker cp mddb-server:/app/data/backup-${DATE}.db \ ${BACKUP_DIR}/ find ${BACKUP_DIR} -name "backup-*.db" -mtime +7 -delete
Monitoring
services: mddb: labels: - "prometheus.scrape=true" - "prometheus.port=11023" - "prometheus.path=/v1/stats"
See Also
- Deployment Guide - General deployment instructions
- API Documentation - API reference
- Architecture - System architecture
License
BSD 3-Clause License - see LICENSE for details.