Docker deployment improvements: fixed backup/restore, sticky headers, quality code display
This commit is contained in:
ske087
303
DOCKER_DEPLOYMENT_GUIDE.md
Normal file
303
DOCKER_DEPLOYMENT_GUIDE.md
Normal file
@@ -0,0 +1,303 @@
|
||||
# Quality Application - Docker Deployment Guide
|
||||
|
||||
## 📋 Overview
|
||||
|
||||
This application is containerized with Docker and docker-compose, providing:
|
||||
- **MariaDB 11.3** database with persistent storage
|
||||
- **Flask** web application with Gunicorn
|
||||
- **Mapped volumes** for easy access to code, data, and backups
|
||||
|
||||
## 🗂️ Volume Structure
|
||||
|
||||
```
|
||||
quality_app/
|
||||
├── data/
|
||||
│ └── mariadb/ # Database files (MariaDB data directory)
|
||||
├── config/
|
||||
│ └── instance/ # Application configuration (external_server.conf)
|
||||
├── logs/ # Application and Gunicorn logs
|
||||
├── backups/ # Database backup files (shared with DB container)
|
||||
└── py_app/ # Application source code (optional mapping)
|
||||
```
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### 1. Setup Volumes
|
||||
|
||||
```bash
|
||||
# Create necessary directories
|
||||
bash setup-volumes.sh
|
||||
```
|
||||
|
||||
### 2. Configure Environment
|
||||
|
||||
```bash
|
||||
# Create .env file from example
|
||||
cp .env.example .env
|
||||
|
||||
# Edit configuration (IMPORTANT: Change passwords!)
|
||||
nano .env
|
||||
```
|
||||
|
||||
**Critical settings to change:**
|
||||
- `MYSQL_ROOT_PASSWORD` - Database root password
|
||||
- `DB_PASSWORD` - Application database password
|
||||
- `SECRET_KEY` - Flask secret key (generate random string)
|
||||
|
||||
**First deployment settings:**
|
||||
- `INIT_DB=true` - Initialize database schema
|
||||
- `SEED_DB=true` - Seed with default data
|
||||
|
||||
**After first deployment:**
|
||||
- `INIT_DB=false`
|
||||
- `SEED_DB=false`
|
||||
|
||||
### 3. Deploy Application
|
||||
|
||||
**Option A: Automated deployment**
|
||||
```bash
|
||||
bash quick-deploy.sh
|
||||
```
|
||||
|
||||
**Option B: Manual deployment**
|
||||
```bash
|
||||
# Build images
|
||||
docker-compose build
|
||||
|
||||
# Start services
|
||||
docker-compose up -d
|
||||
|
||||
# View logs
|
||||
docker-compose logs -f
|
||||
```
|
||||
|
||||
## 📦 Application Dependencies
|
||||
|
||||
### Python Packages (from requirements.txt):
|
||||
- Flask - Web framework
|
||||
- Flask-SSLify - SSL support
|
||||
- Werkzeug - WSGI utilities
|
||||
- gunicorn - Production WSGI server
|
||||
- pyodbc - ODBC database connectivity
|
||||
- mariadb - MariaDB connector
|
||||
- reportlab - PDF generation
|
||||
- requests - HTTP library
|
||||
- pandas - Data manipulation
|
||||
- openpyxl - Excel file support
|
||||
- APScheduler - Job scheduling for automated backups
|
||||
|
||||
### System Dependencies (handled in Dockerfile):
|
||||
- Python 3.10
|
||||
- MariaDB client libraries
|
||||
- curl (for health checks)
|
||||
|
||||
## 🐳 Docker Images
|
||||
|
||||
### Web Application
|
||||
- **Base**: python:3.10-slim
|
||||
- **Multi-stage build** for minimal image size
|
||||
- **Non-root user** for security
|
||||
- **Health checks** enabled
|
||||
|
||||
### Database
|
||||
- **Image**: mariadb:11.3
|
||||
- **Persistent storage** with volume mapping
|
||||
- **Performance tuning** via environment variables
|
||||
|
||||
## 📊 Resource Limits
|
||||
|
||||
### Database Container
|
||||
- CPU: 2.0 cores (limit), 0.5 cores (reserved)
|
||||
- Memory: 2GB (limit), 512MB (reserved)
|
||||
- Buffer pool: 512MB
|
||||
|
||||
### Web Container
|
||||
- CPU: 2.0 cores (limit), 0.5 cores (reserved)
|
||||
- Memory: 2GB (limit), 512MB (reserved)
|
||||
- Workers: 5 Gunicorn workers
|
||||
|
||||
## 🔧 Common Operations
|
||||
|
||||
### View Logs
|
||||
```bash
|
||||
# Application logs
|
||||
docker-compose logs -f web
|
||||
|
||||
# Database logs
|
||||
docker-compose logs -f db
|
||||
|
||||
# All logs
|
||||
docker-compose logs -f
|
||||
```
|
||||
|
||||
### Restart Services
|
||||
```bash
|
||||
# Restart all
|
||||
docker-compose restart
|
||||
|
||||
# Restart specific service
|
||||
docker-compose restart web
|
||||
docker-compose restart db
|
||||
```
|
||||
|
||||
### Stop Services
|
||||
```bash
|
||||
# Stop (keeps data)
|
||||
docker-compose down
|
||||
|
||||
# Stop and remove volumes (WARNING: deletes database!)
|
||||
docker-compose down -v
|
||||
```
|
||||
|
||||
### Update Application Code
|
||||
|
||||
**Without rebuilding (development mode):**
|
||||
1. Uncomment volume mapping in docker-compose.yml:
|
||||
```yaml
|
||||
- ${APP_CODE_PATH}:/app:ro
|
||||
```
|
||||
2. Edit code in `./py_app/`
|
||||
3. Restart: `docker-compose restart web`
|
||||
|
||||
**With rebuilding (production mode):**
|
||||
```bash
|
||||
docker-compose build --no-cache web
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
### Database Access
|
||||
|
||||
**MySQL shell inside container:**
|
||||
```bash
|
||||
docker-compose exec db mysql -u trasabilitate -p
|
||||
# Enter password: Initial01! (or your custom password)
|
||||
```
|
||||
|
||||
**From host machine:**
|
||||
```bash
|
||||
mysql -h 127.0.0.1 -P 3306 -u trasabilitate -p
|
||||
```
|
||||
|
||||
**Root access:**
|
||||
```bash
|
||||
docker-compose exec db mysql -u root -p
|
||||
```
|
||||
|
||||
## 💾 Backup Operations
|
||||
|
||||
### Manual Backup
|
||||
```bash
|
||||
# Full backup
|
||||
docker-compose exec db mysqldump -u trasabilitate -pInitial01! trasabilitate > backups/manual_$(date +%Y%m%d_%H%M%S).sql
|
||||
|
||||
# Data-only backup
|
||||
docker-compose exec db mysqldump -u trasabilitate -pInitial01! --no-create-info trasabilitate > backups/data_only_$(date +%Y%m%d_%H%M%S).sql
|
||||
|
||||
# Structure-only backup
|
||||
docker-compose exec db mysqldump -u trasabilitate -pInitial01! --no-data trasabilitate > backups/structure_only_$(date +%Y%m%d_%H%M%S).sql
|
||||
```
|
||||
|
||||
### Automated Backups
|
||||
The application includes a built-in scheduler for automated backups. Configure via the web interface.
|
||||
|
||||
### Restore from Backup
|
||||
```bash
|
||||
# Stop application (keeps database running)
|
||||
docker-compose stop web
|
||||
|
||||
# Restore database
|
||||
docker-compose exec -T db mysql -u trasabilitate -pInitial01! trasabilitate < backups/backup_file.sql
|
||||
|
||||
# Start application
|
||||
docker-compose start web
|
||||
```
|
||||
|
||||
## 🔍 Troubleshooting
|
||||
|
||||
### Container won't start
|
||||
```bash
|
||||
# Check logs
|
||||
docker-compose logs db
|
||||
docker-compose logs web
|
||||
|
||||
# Check if ports are available
|
||||
ss -tulpn | grep 8781
|
||||
ss -tulpn | grep 3306
|
||||
```
|
||||
|
||||
### Database connection failed
|
||||
```bash
|
||||
# Check database is healthy
|
||||
docker-compose ps
|
||||
|
||||
# Test database connection
|
||||
docker-compose exec db mysqladmin ping -u root -p
|
||||
|
||||
# Check database users
|
||||
docker-compose exec db mysql -u root -p -e "SELECT User, Host FROM mysql.user;"
|
||||
```
|
||||
|
||||
### Permission issues
|
||||
```bash
|
||||
# Check directory permissions
|
||||
ls -la data/mariadb
|
||||
ls -la logs
|
||||
ls -la backups
|
||||
|
||||
# Fix permissions if needed
|
||||
chmod -R 755 data logs backups config
|
||||
```
|
||||
|
||||
### Reset everything (WARNING: deletes all data!)
|
||||
```bash
|
||||
# Stop and remove containers, volumes
|
||||
docker-compose down -v
|
||||
|
||||
# Remove volume directories
|
||||
rm -rf data/mariadb/* logs/* config/instance/*
|
||||
|
||||
# Start fresh
|
||||
bash quick-deploy.sh
|
||||
```
|
||||
|
||||
## 🔒 Security Notes
|
||||
|
||||
1. **Change default passwords** in .env file
|
||||
2. **Generate new SECRET_KEY** for Flask
|
||||
3. Never commit .env file to version control
|
||||
4. Use firewall rules to restrict database port (3306) access
|
||||
5. Consider using Docker secrets for sensitive data in production
|
||||
6. Regular security updates: `docker-compose pull && docker-compose up -d`
|
||||
|
||||
## 🌐 Port Mapping
|
||||
|
||||
- **8781** - Web application (configurable via APP_PORT in .env)
|
||||
- **3306** - MariaDB database (configurable via DB_PORT in .env)
|
||||
|
||||
## 📁 Configuration Files
|
||||
|
||||
- **docker-compose.yml** - Service orchestration
|
||||
- **.env** - Environment variables and configuration
|
||||
- **Dockerfile** - Web application image definition
|
||||
- **docker-entrypoint.sh** - Container initialization script
|
||||
- **init-db.sql** - Database initialization script
|
||||
|
||||
## 🎯 Production Checklist
|
||||
|
||||
- [ ] Change all default passwords
|
||||
- [ ] Generate secure SECRET_KEY
|
||||
- [ ] Set FLASK_ENV=production
|
||||
- [ ] Configure resource limits appropriately
|
||||
- [ ] Set up backup schedule
|
||||
- [ ] Configure firewall rules
|
||||
- [ ] Set up monitoring and logging
|
||||
- [ ] Test backup/restore procedures
|
||||
- [ ] Document deployment procedure for your team
|
||||
- [ ] Set INIT_DB=false and SEED_DB=false after first deployment
|
||||
|
||||
## 📞 Support
|
||||
|
||||
For issues or questions, refer to:
|
||||
- Documentation in `documentation/` folder
|
||||
- Docker logs: `docker-compose logs -f`
|
||||
- Application logs: `./logs/` directory
|
||||
Reference in New Issue
Block a user