411 lines
8.7 KiB
Markdown
411 lines
8.7 KiB
Markdown
# Docker Deployment Guide
|
|
|
|
Complete guide for deploying the Delphi Consulting Group Database System using Docker.
|
|
|
|
## 🐳 Quick Start
|
|
|
|
### Development Mode
|
|
```bash
|
|
# Start with hot reload
|
|
docker-compose -f docker-compose.dev.yml up
|
|
|
|
# Access the application
|
|
http://localhost:6920
|
|
```
|
|
|
|
### Production Mode
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# Build both dev and production images
|
|
./docker-build.sh
|
|
```
|
|
|
|
### 3. Docker Compose Build
|
|
```bash
|
|
# Development
|
|
docker-compose -f docker-compose.dev.yml build
|
|
|
|
# Production
|
|
docker-compose build
|
|
```
|
|
|
|
## 🚀 Deployment Options
|
|
|
|
### Development Deployment
|
|
Best for development, testing, and debugging.
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
**Key Production Settings:**
|
|
```env
|
|
# 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:
|
|
|
|
```yaml
|
|
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:
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
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`:
|
|
```yaml
|
|
services:
|
|
delphi-db:
|
|
deploy:
|
|
resources:
|
|
limits:
|
|
cpus: '1.0'
|
|
memory: 1G
|
|
reservations:
|
|
cpus: '0.5'
|
|
memory: 512M
|
|
```
|
|
|
|
## 🛠️ Maintenance
|
|
|
|
### Updates
|
|
```bash
|
|
# Pull latest images
|
|
docker-compose pull
|
|
|
|
# Rebuild and restart
|
|
docker-compose up -d --build
|
|
|
|
# Clean up old images
|
|
docker image prune -f
|
|
```
|
|
|
|
### Scaling
|
|
```bash
|
|
# Scale application containers
|
|
docker-compose up -d --scale delphi-db=3
|
|
|
|
# Load balancing requires additional configuration
|
|
```
|
|
|
|
### Troubleshooting
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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](README.md) for additional information or contact your system administrator. |