site_backend/DOCKER_README.md

Docker Setup for Zoneco ORG Backend

This document provides instructions for running the Zoneco ORG backend using Docker and Docker Compose.

Prerequisites

• Docker Engine 20.10 or higher
• Docker Compose 2.0 or higher

Quick Start

1. Navigate to the backend directory:

   cd backend
   

2. Create a .env file (copy from the template below):

   # Copy and modify as needed
   SECRET_KEY=your-secret-key-here-change-in-production
   DEBUG=False
   ALLOWED_HOSTS=localhost,127.0.0.1,YOUR_SERVER_IP
   POSTGRES_DB=Zoneco_ORG
   POSTGRES_USER=postgres
   POSTGRES_PASSWORD=change-me
   POSTGRES_HOST=db
   POSTGRES_PORT=5432
   DJANGO_PORT=8000
   ADMIN_USERNAME=your-admin-username
   ADMIN_PASSWORD=your-admin-password
   CORS_ALLOWED_ORIGINS=http://localhost:5173,http://localhost:3000,http://YOUR_SERVER_IP:9123
   

3. Build and start the containers:

   docker-compose up --build
   

4. The application will be available at:

   • API: http://localhost:8000/api/
   • Admin: http://localhost:8000/admin/

Docker Commands

Start services

docker-compose up

Start services in detached mode

docker-compose up -d

Stop services

docker-compose down

Stop services and remove volumes (⚠️ deletes database data)

docker-compose down -v

View logs

docker-compose logs -f

View logs for specific service

docker-compose logs -f web
docker-compose logs -f db

Rebuild containers

docker-compose build --no-cache

Execute commands in running container

# Django shell
docker-compose exec web python manage.py shell

# Create superuser
docker-compose exec web python manage.py createsuperuser

# Run migrations manually
docker-compose exec web python manage.py migrate

# Collect static files
docker-compose exec web python manage.py collectstatic --noinput

Architecture

The Docker setup consists of:

1. Web Service (web):

   • Django application running with Gunicorn
   • Multi-stage Dockerfile for optimized image size
   • Non-root user for security
   • Automatic migrations and static file collection on startup
   • Health checks enabled

2. Database Service (db):

   • PostgreSQL 15 Alpine (lightweight)
   • Persistent data volume
   • Health checks to ensure readiness

Features

Security Best Practices

• ✅ Multi-stage build for smaller image size
• ✅ Non-root user execution
• ✅ Environment variable configuration
• ✅ No hardcoded secrets
• ✅ Health checks for both services

Production Ready

• ✅ Gunicorn WSGI server
• ✅ Automatic database migrations
• ✅ Static file collection
• ✅ Database connection retry logic
• ✅ Proper logging

Development Friendly

• ✅ Volume mounts for media and static files
• ✅ Hot-reload capability (with proper setup)
• ✅ Easy access to Django management commands

Environment Variables

Variable	Description	Default
SECRET_KEY	Django secret key	(required in production)
DEBUG	Enable debug mode	False
ALLOWED_HOSTS	Comma-separated allowed hosts	localhost,127.0.0.1
POSTGRES_DB	Database name	Zoneco_ORG
POSTGRES_USER	Database user	postgres
POSTGRES_PASSWORD	Database password	postgres
POSTGRES_HOST	Database host	db
POSTGRES_PORT	Database port	5432
DJANGO_PORT	Django application port	8000
CORS_ALLOWED_ORIGINS	Comma-separated CORS origins	(see .env.example)

Volumes

• postgres_data: Persistent PostgreSQL data
• ./media: Media files (images, uploads)
• ./staticfiles: Collected static files

Troubleshooting

Database connection errors

# Check if database is healthy
docker-compose ps

# Check database logs
docker-compose logs db

# Restart services
docker-compose restart

Permission issues

# Fix media/staticfiles permissions
sudo chown -R $USER:$USER media staticfiles

Port already in use

# Change port in .env file
DJANGO_PORT=8001
# Then update docker-compose.yml or restart

Clear everything and start fresh

docker-compose down -v
docker-compose build --no-cache
docker-compose up

Production Deployment

For production deployment:

1. Set strong SECRET_KEY:

   python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"
   

2. Set DEBUG=False in .env

3. Configure proper ALLOWED_HOSTS

4. Use strong database passwords

5. Consider using:

   • Reverse proxy (nginx)
   • SSL/TLS certificates
   • Separate database server
   • Backup strategy
   • Monitoring and logging

File Structure

backend/
├── Dockerfile              # Multi-stage production Dockerfile
├── docker-compose.yml      # Service orchestration
├── .dockerignore          # Files to exclude from build
├── entrypoint.sh          # Startup script
├── requirements.txt       # Python dependencies
└── DOCKER_README.md       # This file