petpicturequeue/README_DOCKER.md

Docker Setup for Pets of Powerwashing

Updated for Refactored Architecture

The Docker setup has been updated to work with the refactored Flask application structure.

Quick Start

1. Build and Run

# Build and start the application
docker compose up --build

# Or run in detached mode
docker compose up --build -d

2. Run Database Migration

# Run the migration (first time setup or after schema changes)
docker compose --profile migrate up migrate

3. Access the Application

• Web Interface: http://localhost:54321
• Admin Login: username: admin, password: password123

File Structure Changes

The refactored application now uses this structure:

app/
├── static/uploads/     # Upload directory (mounted as volume)
├── templates/          # HTML templates
├── models/            # Database models
├── routes/            # Route handlers (blueprints)
├── utils/             # Utilities and helpers
└── ...

Docker Configuration

Environment Variables

You can customize the application through environment variables:

environment:
  # Flask settings
  - FLASK_ENV=production
  
  # Application settings
  - UPLOAD_FOLDER=app/static/uploads
  - DATABASE_PATH=pet_pictures.db
  - ADMIN_USERNAME=admin
  - ADMIN_PASSWORD=password123
  
  # Optional: Override secret key for production
  - SECRET_KEY=your-secret-key-here

Volume Mounts

• ./app/static/uploads:/app/app/static/uploads - Persistent file uploads
• ./pet_pictures.db:/app/pet_pictures.db - Persistent database

Services

Web Service (web)

• Port: 54321 (maps to internal port 5000)
• Process: Gunicorn with 4 workers
• Health Check: HTTP check every 30 seconds
• Restart Policy: unless-stopped

Migration Service (migrate)

• Purpose: Database schema updates
• Usage: docker compose --profile migrate up migrate
• Script: Uses migrate_session_changes.py

Commands

Development

# Build only
docker compose build

# View logs
docker compose logs -f

# Stop services
docker compose down

# Remove everything including volumes
docker compose down -v

Production

# Start in production mode
FLASK_ENV=production docker compose up -d

# Update and restart
docker compose pull
docker compose up --build -d

Troubleshooting

Common Issues

1. Permission Issues with Uploads

# Fix upload directory permissions
sudo chown -R 1000:1000 ./app/static/uploads

2. Database Migration Fails

# Run migration manually
docker compose exec web python migrate_session_changes.py

3. Build Fails

# Clean build
docker compose build --no-cache

Health Check

The application includes a health check that:

• Tests HTTP connectivity on port 5000
• Retries 3 times with 5-second delays
• Runs every 30 seconds
• Allows 40 seconds for startup

Security Notes

For Production:

1. Change default admin credentials via environment variables
2. Set a secure SECRET_KEY
3. Use HTTPS reverse proxy (nginx/traefik)
4. Limit file upload sizes
5. Regular database backups

File Locations in Container

• Application: /app/
• Database: /app/pet_pictures.db
• Uploads: /app/app/static/uploads/
• Logs: /app/logs/ (if logging enabled)

Changes from Previous Version

✅ Updated paths for refactored app structure
✅ New migration script (migrate_session_changes.py)
✅ Added environment variables for configuration
✅ Improved .dockerignore for smaller builds
✅ Removed obsolete version from docker-compose.yml
✅ Better volume mapping for uploads directory