quality_app/DOCKER_DEPLOYMENT_GUIDE.md

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

# Create necessary directories
bash setup-volumes.sh

2. Configure Environment

# 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 quick-deploy.sh

Option B: Manual deployment

# 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

# Application logs
docker-compose logs -f web

# Database logs
docker-compose logs -f db

# All logs
docker-compose logs -f

Restart Services

# Restart all
docker-compose restart

# Restart specific service
docker-compose restart web
docker-compose restart db

Stop Services

# 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:

   - ${APP_CODE_PATH}:/app:ro
   

2. Edit code in ./py_app/
3. Restart: docker-compose restart web

With rebuilding (production mode):

docker-compose build --no-cache web
docker-compose up -d

Database Access

MySQL shell inside container:

docker-compose exec db mysql -u trasabilitate -p
# Enter password: Initial01! (or your custom password)

From host machine:

mysql -h 127.0.0.1 -P 3306 -u trasabilitate -p

Root access:

docker-compose exec db mysql -u root -p

💾 Backup Operations

Manual Backup

# 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

# 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

# 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

# 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

# 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!)

# 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