315 lines
6.8 KiB
Markdown
315 lines
6.8 KiB
Markdown
# 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)
|