304 lines
7.0 KiB
Markdown
304 lines
7.0 KiB
Markdown
# 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
|