groceries/DOCKER_DEPLOYMENT.md

Docker Deployment Guide

This guide explains how to deploy your Groceries/Product Tracker application using Docker Compose.

Prerequisites

• Docker Engine 20.10+
• Docker Compose 2.0+
• Git (for cloning from your Gitea repository)

Quick Start

1. Clone your repository from Gitea:

   git clone <your-gitea-repo-url>
   cd groceries
   

2. Set up environment variables:

   cp docker.env.example .env
   # Edit .env with your production values
   nano .env
   

3. Build and start all services:

   docker-compose up -d
   

4. Access your application:

   • Frontend: http://localhost
   • Backend API: http://localhost:8000
   • API Documentation: http://localhost:8000/docs

Architecture

The Docker Compose setup includes:

• PostgreSQL Database (port 5432)
• FastAPI Backend (port 8000)
• React Frontend with Nginx (port 80)

Environment Configuration

Required Environment Variables

Create a .env file in the root directory:

# Database Configuration
DB_PASSWORD=your_secure_database_password

# Backend Configuration
SECRET_KEY=your-super-secret-key-for-jwt-tokens-make-it-very-long-and-random
DEBUG=False

Optional Configuration

You can override default ports by adding to your .env file:

# Custom ports (optional)
FRONTEND_PORT=3000
BACKEND_PORT=8001
DB_PORT=5433

Then update the docker-compose.yml ports section accordingly.

Deployment Commands

Development Deployment

# Start all services
docker-compose up

# Start in background
docker-compose up -d

# View logs
docker-compose logs -f

# View logs for specific service
docker-compose logs -f backend

Production Deployment

1. Set production environment:

   export COMPOSE_FILE=docker-compose.yml
   export COMPOSE_PROJECT_NAME=groceries_prod
   

2. Use production environment file:

   cp docker.env.example .env.prod
   # Edit .env.prod with production values
   docker-compose --env-file .env.prod up -d
   

3. Run database migrations:

   docker-compose exec backend alembic upgrade head
   

Database Management

Initial Setup

The database will be automatically created when you first start the services. To run migrations:

# Run migrations
docker-compose exec backend alembic upgrade head

# Create new migration (if you've made model changes)
docker-compose exec backend alembic revision --autogenerate -m "Description"

Backup and Restore

# Backup database
docker-compose exec db pg_dump -U product_user product_tracker > backup.sql

# Restore database
docker-compose exec -T db psql -U product_user product_tracker < backup.sql

Service Management

Individual Service Control

# Restart specific service
docker-compose restart backend

# Rebuild and restart service
docker-compose up -d --build backend

# Scale services (if needed)
docker-compose up -d --scale backend=2

Updating the Application

# Pull latest code from Gitea
git pull origin main

# Rebuild and restart services
docker-compose down
docker-compose up -d --build

Monitoring and Logs

View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f backend
docker-compose logs -f frontend
docker-compose logs -f db

# Last 100 lines
docker-compose logs --tail=100 backend

Health Checks

The services include health checks. Check status:

docker-compose ps

Resource Usage

# View resource usage
docker stats

# View specific containers
docker stats groceries_backend groceries_frontend groceries_db

Troubleshooting

Common Issues

1. Port conflicts:

   # Check what's using the port
   lsof -i :80
   lsof -i :8000
   lsof -i :5432
   
   # Change ports in .env file or docker-compose.yml
   

2. Database connection issues:

   # Check database logs
   docker-compose logs db
   
   # Test database connection
   docker-compose exec db psql -U product_user -d product_tracker -c "SELECT 1;"
   

3. Backend not starting:

   # Check backend logs
   docker-compose logs backend
   
   # Exec into container to debug
   docker-compose exec backend bash
   

4. Frontend not loading:

   # Check nginx logs
   docker-compose logs frontend
   
   # Verify build completed successfully
   docker-compose exec frontend ls -la /usr/share/nginx/html
   

Reset Everything

# Stop and remove all containers, networks, and volumes
docker-compose down -v

# Remove all images
docker-compose down --rmi all

# Start fresh
docker-compose up -d --build

Security Considerations

Production Security

1. Change default passwords:

   • Update DB_PASSWORD in .env
   • Generate a strong SECRET_KEY

2. Use HTTPS:

   • Add SSL certificates
   • Configure nginx for HTTPS
   • Update docker-compose.yml with SSL configuration

3. Network security:

   • Remove port mappings for internal services
   • Use Docker secrets for sensitive data
   • Configure firewall rules

4. Regular updates:

   • Keep Docker images updated
   • Update application dependencies
   • Monitor security advisories

Example Production docker-compose.yml

For production, consider:

# Remove port mappings for internal services
services:
  db:
    # Remove: ports: - "5432:5432"
    
  backend:
    # Remove: ports: - "8000:8000"
    
  frontend:
    ports:
      - "443:443"  # HTTPS
      - "80:80"     # HTTP redirect

Gitea Integration

Automated Deployment

You can set up automated deployment from your Gitea repository:

1. Create a webhook in your Gitea repository
2. Set up a deployment script on your server:

#!/bin/bash
# deploy.sh
cd /path/to/your/app
git pull origin main
docker-compose down
docker-compose up -d --build

3. Configure webhook to trigger the deployment script

CI/CD Pipeline

Consider setting up Gitea Actions or external CI/CD:

# .gitea/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Deploy to server
        run: |
          # Your deployment commands
          docker-compose up -d --build

Performance Optimization

Production Optimizations

1. Use multi-stage builds (already implemented)
2. Enable gzip compression in nginx
3. Add caching headers (already configured)
4. Use connection pooling for database
5. Configure resource limits:

services:
  backend:
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: '0.5'

Backup Strategy

Automated Backups

#!/bin/bash
# backup.sh
DATE=$(date +%Y%m%d_%H%M%S)
docker-compose exec -T db pg_dump -U product_user product_tracker > "backup_${DATE}.sql"
# Upload to cloud storage or remote location

Set up a cron job:

# Run daily at 2 AM
0 2 * * * /path/to/backup.sh

This setup provides a robust, production-ready deployment of your groceries application using Docker Compose!