# 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

```bash
# 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:**
```bash
# 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

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

### 4. Start Services

```bash
# Start in detached mode
docker-compose up -d

# Watch logs
docker-compose logs -f web
```

### 5. After First Successful Start

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

# Restart to apply changes
docker-compose restart web
```

## Common Commands

### Service Management

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:
   ```bash
   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):
```bash
docker-compose up -d --build
```

## Troubleshooting

### Application won't start

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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](./documentation/PRODUCTION_STARTUP_GUIDE.md) - Application management
- [DATABASE_BACKUP_GUIDE.md](./documentation/DATABASE_BACKUP_GUIDE.md) - Backup procedures
- [DATABASE_RESTORE_GUIDE.md](./documentation/DATABASE_RESTORE_GUIDE.md) - Restore procedures
- [DATABASE_STRUCTURE.md](./documentation/DATABASE_STRUCTURE.md) - Database schema

---

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