hotswap/delphi-database
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f0eecdf83e1a09fc14da5cd707f0282b7e9b3a52
delphi-database/docs/DOCKER.md
HotSwapp 21c6b285d6 clean up docs
2025-08-14 21:40:49 -05:00

8.7 KiB
Raw Blame History

Docker Deployment Guide

Complete guide for deploying the Delphi Consulting Group Database System using Docker.

🐳 Quick Start

Development Mode

# Start with hot reload
docker-compose -f docker-compose.dev.yml up

# Access the application
http://localhost:6920

Production Mode

# Start production services
docker-compose up -d

# With Nginx proxy (optional)
docker-compose --profile production up -d

📋 Prerequisites

  • Docker 20.10+
  • Docker Compose 2.0+
  • 2GB free disk space
  • Port 6920 available (or configure different port)

🛠️ Build Options

1. Quick Build

# Build development image
docker build -t delphi-database:dev .

# Build production image  
docker build -f Dockerfile.production -t delphi-database:prod .

2. Automated Build Script

# Build both dev and production images
./docker-build.sh

3. Docker Compose Build

# Development
docker-compose -f docker-compose.dev.yml build

# Production
docker-compose build

🚀 Deployment Options

Development Deployment

Best for development, testing, and debugging.

# Set up secure configuration (recommended)
python scripts/setup-security.py

# OR manually copy and edit
cp .env.example .env
nano .env

# Start services
docker-compose -f docker-compose.dev.yml up

Features:

  • Hot reload enabled
  • Debug mode on
  • Source code mounted as volume
  • Extended token expiration
  • Direct port access

Production Deployment

Optimized for production use.

# Set up secure configuration (recommended)  
python scripts/setup-security.py

# OR manually configure
cp .env.example .env
nano .env  # Set production values

# Start production services
docker-compose up -d

# Check status
docker-compose ps
docker-compose logs -f delphi-db

Features:

  • Multi-worker Gunicorn server
  • Optimized image size
  • Health checks enabled
  • Persistent data volumes
  • Optional Nginx reverse proxy

Production with Nginx

Full production setup with reverse proxy, SSL termination, and rate limiting.

# Configure SSL certificates (if using HTTPS)
mkdir -p nginx/ssl
# Copy your SSL certificates to nginx/ssl/

# Start with Nginx
docker-compose --profile production up -d

# Available on port 80 (HTTP) and 443 (HTTPS)

🔧 Configuration

Security Setup (Recommended)

Use the automated security setup script to generate secure keys and configuration:

# Interactive setup with secure defaults
python scripts/setup-security.py

# Generate just a secret key
python scripts/setup-security.py --key-only

# Generate just a password
python scripts/setup-security.py --password-only

The script will:

  • Generate a cryptographically secure SECRET_KEY
  • Create a strong admin password
  • Set up proper CORS origins
  • Configure all environment variables
  • Set secure file permissions (600) on .env

Environment Variables

Create .env file from template:

cp .env.example .env

Key Production Settings:

# Security (CRITICAL - Change in production!)
SECRET_KEY=your-super-secure-secret-key-here
DEBUG=False

# Database path (inside container)
DATABASE_URL=sqlite:///data/delphi_database.db

# Admin user creation (optional)
CREATE_ADMIN_USER=true
ADMIN_USERNAME=admin
ADMIN_EMAIL=admin@yourcompany.com
ADMIN_PASSWORD=secure-admin-password
ADMIN_FULLNAME=System Administrator

# Server settings
HOST=0.0.0.0
PORT=8000
WORKERS=4

Volume Mapping

The system uses Docker volumes for persistent data:

volumes:
  - delphi_data:/app/data          # Database files
  - delphi_uploads:/app/uploads    # File uploads
  - delphi_backups:/app/backups    # Database backups

Port Configuration

Default ports:

  • 6920: Application (development/production)
  • 80: Nginx HTTP (production)
  • 443: Nginx HTTPS (production)

To use different ports:

# Custom port mapping
docker run -p 9000:8000 delphi-database:latest

# Or edit docker-compose.yml ports section:
ports:
  - "YOUR_PORT:8000"

📊 Data Management

Initial Setup

The container automatically:

  1. Creates database tables on first run
  2. Creates admin user (if CREATE_ADMIN_USER=true)
  3. Sets up necessary directories

Database Backups

# Manual backup
docker exec delphi-database /app/scripts/backup.sh

# Scheduled backups (cron example)
0 2 * * * docker exec delphi-database /app/scripts/backup.sh

Database Restore

# List available backups
docker exec delphi-database ls -la /app/backups/

# Restore from backup
docker exec delphi-database /app/scripts/restore.sh delphi_backup_20241207_143000.db

# Restart container after restore
docker-compose restart delphi-db

Data Import/Export

# Export customer data
docker exec delphi-database curl -X GET "http://localhost:8000/api/admin/export/customers" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o customers_export.csv

# Import CSV data (via web interface or API)

📝 Monitoring & Logs

Health Checks

# Check container health
docker ps

# Test health endpoint
curl http://localhost:6920/health

# View health check logs
docker inspect --format='{{json .State.Health}}' delphi-database | jq

Viewing Logs

# Follow application logs
docker-compose logs -f delphi-db

# View specific service logs
docker-compose logs nginx

# Container logs
docker logs delphi-database

System Monitoring

# Container stats
docker stats delphi-database

# System info  
docker exec delphi-database curl -s http://localhost:8000/api/admin/stats

🔒 Security Considerations

Production Security Checklist

  • Change SECRET_KEY in production
  • Set DEBUG=False
  • Use strong admin passwords
  • Configure SSL certificates
  • Set up proper firewall rules
  • Enable container resource limits
  • Regular security updates

SSL/HTTPS Setup

  1. Obtain SSL certificates (Let's Encrypt, commercial, etc.)
  2. Copy certificates to nginx/ssl/ directory: 
    cp your-cert.pem nginx/ssl/cert.pem
cp your-key.pem nginx/ssl/key.pem
  3. Uncomment HTTPS section in nginx/nginx.conf
  4. Restart Nginx: docker-compose restart nginx

Resource Limits

Add resource limits to docker-compose.yml:

services:
  delphi-db:
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 1G
        reservations:
          cpus: '0.5'
          memory: 512M

🛠️ Maintenance

Updates

# Pull latest images
docker-compose pull

# Rebuild and restart
docker-compose up -d --build

# Clean up old images
docker image prune -f

Scaling

# Scale application containers
docker-compose up -d --scale delphi-db=3

# Load balancing requires additional configuration

Troubleshooting

# Enter container for debugging
docker exec -it delphi-database /bin/bash

# Check database
docker exec -it delphi-database sqlite3 /app/data/delphi_database.db

# Reset containers
docker-compose down
docker-compose up -d --force-recreate

# Clean restart (WARNING: Removes all data)
docker-compose down -v
docker-compose up -d

📁 File Structure

delphi-database/
├── Dockerfile              # Development image
├── Dockerfile.production    # Production optimized image  
├── docker-compose.yml       # Production compose
├── docker-compose.dev.yml   # Development compose
├── docker-build.sh          # Build script
├── .dockerignore           # Docker ignore rules
├── .env.example            # Environment template
├── nginx/
│   ├── nginx.conf          # Nginx configuration
│   └── ssl/                # SSL certificates
└── scripts/
    ├── init-container.sh   # Container initialization
    ├── backup.sh           # Database backup
    └── restore.sh          # Database restore

🚨 Emergency Procedures

System Recovery

# Stop all services
docker-compose down

# Backup current data
docker cp delphi-database:/app/data ./emergency-backup/

# Restore from last known good backup
docker-compose up -d
docker exec delphi-database /app/scripts/restore.sh <backup-file>

Performance Issues

# Check resource usage
docker stats

# Increase resources in docker-compose.yml
# Restart services
docker-compose restart

🎯 Production Checklist

Before deploying to production:

  • Set secure SECRET_KEY
  • Configure proper database backups
  • Set up SSL certificates
  • Configure monitoring/alerting
  • Test restore procedures
  • Document admin credentials
  • Set up firewall rules
  • Configure log rotation
  • Test all API endpoints
  • Verify keyboard shortcuts work
  • Load test the application

Need Help? Check the main README.md for additional information or contact your system administrator.

Reference in New Issue View Git Blame Copy Permalink