# 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