quality_app/documentation/DOCKER_QUICK_START.md

Docker Compose - Quick Reference

Simplified Structure

The Docker Compose configuration has been simplified with most settings moved to the .env file for easier management.

File Structure

quality_app/
├── docker-compose.yml          # Main Docker configuration (171 lines, simplified)
├── .env.example                # Template with all available settings
├── .env                        # Your configuration (copy from .env.example)
├── Dockerfile                  # Application container definition
├── docker-entrypoint.sh        # Container startup script
└── init-db.sql                 # Database initialization

Quick Start

1. Initial Setup

# Navigate to project directory
cd /srv/quality_app

# Create .env file from template
cp .env.example .env

# Edit .env with your settings
nano .env

2. Configure .env File

Required changes for first deployment:

# Set these to true for first run only
INIT_DB=true
SEED_DB=true

# Change these in production
SECRET_KEY=your-secure-random-key-here
MYSQL_ROOT_PASSWORD=your-secure-root-password
DB_PASSWORD=your-secure-db-password

3. Create Required Directories

sudo mkdir -p /srv/quality_app/{mariadb,logs,backups}
sudo chown -R $USER:$USER /srv/quality_app

4. Start Services

# Start in detached mode
docker-compose up -d

# Watch logs
docker-compose logs -f web

5. After First Successful Start

# Edit .env and set:
INIT_DB=false
SEED_DB=false

# Restart to apply changes
docker-compose restart web

Common Commands

Service Management

# Start services
docker-compose up -d

# Stop services
docker-compose down

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

# View service status
docker-compose ps

# Remove all containers and volumes
docker-compose down -v

Logs and Monitoring

# Follow all logs
docker-compose logs -f

# Follow specific service logs
docker-compose logs -f web
docker-compose logs -f db

# View last 100 lines
docker-compose logs --tail=100 web

# Check resource usage
docker stats quality-app quality-app-db

Updates and Rebuilds

# Rebuild after code changes
docker-compose up -d --build

# Pull latest images
docker-compose pull

# Rebuild specific service
docker-compose up -d --build web

Database Operations

# Access database CLI
docker-compose exec db mysql -u trasabilitate -p trasabilitate

# Backup database
docker-compose exec db mysqldump -u root -p trasabilitate > backup.sql

# Restore database
docker-compose exec -T db mysql -u root -p trasabilitate < backup.sql

# View database logs
docker-compose logs db

Container Access

# Access web application shell
docker-compose exec web bash

# Access database shell
docker-compose exec db bash

# Run one-off command
docker-compose exec web python -c "print('Hello')"

Environment Variables Reference

Critical Settings (.env)

Variable	Default	Description
APP_PORT	8781	Application port
DB_PASSWORD	Initial01!	Database password
SECRET_KEY	change-this	Flask secret key
INIT_DB	false	Initialize database on startup
SEED_DB	false	Seed default data on startup

Volume Paths

Variable	Default	Purpose
DB_DATA_PATH	/srv/quality_app/mariadb	Database files
LOGS_PATH	/srv/quality_app/logs	Application logs
BACKUP_PATH	/srv/quality_app/backups	Database backups
INSTANCE_PATH	/srv/quality_app/py_app/instance	Config files

Performance Tuning

Variable	Default	Description
GUNICORN_WORKERS	auto	Number of workers
GUNICORN_TIMEOUT	1800	Request timeout (seconds)
MYSQL_BUFFER_POOL	256M	Database buffer size
MYSQL_MAX_CONNECTIONS	150	Max DB connections
APP_CPU_LIMIT	2.0	CPU limit for app
APP_MEMORY_LIMIT	1G	Memory limit for app

Configuration Changes

To change configuration:

1. Edit .env file
2. Restart affected service:

   docker-compose restart web
   # or
   docker-compose restart db
   

When to Restart vs Rebuild

Restart only (changes in .env):

• Environment variables
• Resource limits
• Port mappings

Rebuild required (code/Dockerfile changes):

docker-compose up -d --build

Troubleshooting

Application won't start

# Check logs
docker-compose logs web

# Check database health
docker-compose ps
docker-compose exec db mysqladmin ping -u root -p

# Verify .env file
cat .env | grep -v "^#" | grep -v "^$"

Database connection issues

# Check database is running
docker-compose ps db

# Test database connection
docker-compose exec web python -c "
import mysql.connector
conn = mysql.connector.connect(
    host='db', user='trasabilitate', 
    password='Initial01!', database='trasabilitate'
)
print('Connected OK')
"

Port already in use

# Check what's using the port
sudo netstat -tlnp | grep 8781

# Change APP_PORT in .env
echo "APP_PORT=8782" >> .env
docker-compose up -d

Reset everything

# Stop and remove all
docker-compose down -v

# Remove data (CAUTION: destroys database!)
sudo rm -rf /srv/quality_app/mariadb/*

# Restart fresh
INIT_DB=true SEED_DB=true docker-compose up -d

Production Checklist

Before deploying to production:

• Change SECRET_KEY in .env
• Change MYSQL_ROOT_PASSWORD in .env
• Change DB_PASSWORD in .env
• Set INIT_DB=false after first run
• Set SEED_DB=false after first run
• Set FLASK_ENV=production
• Verify backup paths are correct
• Test backup and restore procedures
• Set up external monitoring
• Configure firewall rules
• Set up SSL/TLS certificates
• Review resource limits
• Set up log rotation

Comparison: Before vs After

Before (242 lines)

• Many inline default values
• Extensive comments in docker-compose.yml
• Hard to find and change settings
• Difficult to maintain multiple environments

After (171 lines)

• Clean, readable docker-compose.yml (29% reduction)
• All settings in .env file
• Easy to customize per environment
• Simple to version control (just .env.example)
• Better separation of concerns

Related Documentation

• PRODUCTION_STARTUP_GUIDE.md - Application management
• DATABASE_BACKUP_GUIDE.md - Backup procedures
• DATABASE_RESTORE_GUIDE.md - Restore procedures
• DATABASE_STRUCTURE.md - Database schema

---

Last Updated: November 3, 2025
Docker Compose Version: 3.8
Configuration Style: Environment-based (simplified)