clean up docs
This commit is contained in:
HotSwapp
411
docs/DOCKER.md
Normal file
411
docs/DOCKER.md
Normal file
@@ -0,0 +1,411 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user