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

2. **Create a `.env` file** (copy from the template below):
   ```bash
   # Copy and modify as needed
   SECRET_KEY=your-secret-key-here-change-in-production
   DEBUG=False
   ALLOWED_HOSTS=localhost,127.0.0.1,185.208.172.158
   POSTGRES_DB=Zoneco_ORG
   POSTGRES_USER=postgres
   POSTGRES_PASSWORD=postgres
   POSTGRES_HOST=db
   POSTGRES_PORT=5432
   DJANGO_PORT=8000
   CORS_ALLOWED_ORIGINS=http://localhost:5173,http://localhost:3000,http://127.0.0.1:5173,http://127.0.0.1:3000,http://185.208.172.158:9123,http://185.208.172.158
   ```

3. **Build and start the containers:**
   ```bash
   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
```bash
docker-compose up
```

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

### Stop services
```bash
docker-compose down
```

### Stop services and remove volumes (⚠️ deletes database data)
```bash
docker-compose down -v
```

### View logs
```bash
docker-compose logs -f
```

### View logs for specific service
```bash
docker-compose logs -f web
docker-compose logs -f db
```

### Rebuild containers
```bash
docker-compose build --no-cache
```

### Execute commands in running container
```bash
# 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
```bash
# Check if database is healthy
docker-compose ps

# Check database logs
docker-compose logs db

# Restart services
docker-compose restart
```

### Permission issues
```bash
# Fix media/staticfiles permissions
sudo chown -R $USER:$USER media staticfiles
```

### Port already in use
```bash
# Change port in .env file
DJANGO_PORT=8001
# Then update docker-compose.yml or restart
```

### Clear everything and start fresh
```bash
docker-compose down -v
docker-compose build --no-cache
docker-compose up
```

## Production Deployment

For production deployment:

1. **Set strong SECRET_KEY:**
   ```bash
   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
```