modern-django-starter/DEPLOYMENT_CHECKLIST.md

# 🚀 Django Deployment Checklist - Zero-Fail Guide

Use this checklist to deploy Django projects smoothly every time.

## ✅ **Pre-Deployment Checklist**

### **1. Static Files & Assets**
- [ ] **Build Tailwind CSS locally**: `npm run build` in theme/static_src/
- [ ] **Verify CSS files exist**: Check `theme/static/css/dist/styles.css` exists
- [ ] **Test collectstatic locally**: `python manage.py collectstatic --noinput`
- [ ] **Commit static files**: Ensure built assets are in Git

### **2. Database & Migrations**
- [ ] **Create migrations**: `python manage.py makemigrations`
- [ ] **Test migrations locally**: `python manage.py migrate`
- [ ] **Verify Sites framework**: Check `django.contrib.sites` in INSTALLED_APPS
- [ ] **Test site creation**: Run `python manage.py configure_site` locally

### **3. Environment Configuration**
- [ ] **Update .env.example**: Include all required variables
- [ ] **Document required vars**: List in README what's needed for production
- [ ] **Test with production settings**: `DJANGO_SETTINGS_MODULE=project.settings.production`

### **4. Docker Configuration**
- [ ] **Test Docker build**: `docker build --target production .`
- [ ] **Verify startup script**: Ensure `startup.sh` is executable
- [ ] **Test compose file**: `docker-compose -f docker-compose.dokploy-simple.yml up`

## 🔧 **Deployment Steps (Dokploy)**

### **Step 1: Repository Setup**
- [ ] Push all changes to main branch
- [ ] Verify compose file path is correct in Dokploy
- [ ] Check Dockerfile builds successfully

### **Step 2: Environment Variables** 
Set these in Dokploy environment tab:
```env
SECRET_KEY=your-long-secret-key-here
DEBUG=False
ALLOWED_HOSTS=yourdomain.com,www.yourdomain.com
CSRF_TRUSTED_ORIGINS=https://yourdomain.com
SECURE_SSL_REDIRECT=True
DATABASE_URL=postgresql://... (if using external DB)
```

### **Step 3: Domain Configuration**
- [ ] DNS: Point domain to Dokploy server IP
- [ ] Dokploy Domain: Set service=web, port=8000
- [ ] HTTPS: Enable SSL/Auto SSL
- [ ] Wait 2-3 minutes for SSL certificate

### **Step 4: Deploy & Verify**
- [ ] Deploy application
- [ ] Check deployment logs for errors
- [ ] Test endpoints:
  - [ ] Homepage: `https://yourdomain.com/`
  - [ ] Health: `https://yourdomain.com/health/`
  - [ ] Login: `https://yourdomain.com/accounts/login/`
  - [ ] Admin: `https://yourdomain.com/admin/`

## 🛡️ **Common Issues Prevention**

### **Static Files**
✅ **DO**: Build static files during Docker build  
❌ **DON'T**: Rely on runtime collectstatic with volume mounts

### **Database Migrations** 
✅ **DO**: Run explicit site migration: `migrate sites`  
❌ **DON'T**: Assume all migrations run automatically

### **Environment Variables**
✅ **DO**: Use environment variables for all settings  
❌ **DON'T**: Hardcode production values in settings files

### **Docker Configuration**
✅ **DO**: Use simple port mapping (ports: "8000:8000")  
❌ **DON'T**: Use complex Traefik labels unless necessary

## 🚀 **Quick Deploy Templates**

### **For New Projects** (Copy-Paste Ready)

**docker-compose.dokploy.yml:**
```yaml
services:
  web:
    build: .
    ports:
      - "8000:8000"
    environment:
      - DEBUG=${DEBUG:-False}
      - ALLOWED_HOSTS=${ALLOWED_HOSTS}
      - SECRET_KEY=${SECRET_KEY}
      - DATABASE_URL=${DATABASE_URL:-postgresql://django_user:django_password@db:5432/django_db}
    command: sh -c "chmod +x /app/startup.sh && /app/startup.sh"
    depends_on:
      - db
  
  db:
    image: postgres:15-alpine
    environment:
      - POSTGRES_DB=django_db
      - POSTGRES_USER=django_user  
      - POSTGRES_PASSWORD=django_password
    volumes:
      - postgres_data:/var/lib/postgresql/data/

volumes:
  postgres_data:
```

**startup.sh:**
```bash
#!/bin/bash
set -e
python manage.py migrate --noinput
python manage.py migrate sites --noinput  
python manage.py collectstatic --noinput
exec gunicorn --bind 0.0.0.0:8000 django_project.wsgi:application
```

## 📋 **Environment Variables Template**
```env
SECRET_KEY=generate-long-random-key-here
DEBUG=False
ALLOWED_HOSTS=yourdomain.com
CSRF_TRUSTED_ORIGINS=https://yourdomain.com
SECURE_SSL_REDIRECT=True
DATABASE_URL=postgresql://user:pass@host:5432/db
```

## 🎯 **Time to Deploy: 5 Minutes**

With this checklist, deployment should take:
- ⏱️ **2 min**: Environment setup  
- ⏱️ **2 min**: Docker build & deploy
- ⏱️ **1 min**: SSL certificate generation

**Total: 5 minutes from code to live site!** 🚀

## 🆘 **Emergency Debugging**

If deployment fails:
1. **Check logs**: Look for specific error messages
2. **Test health endpoint**: `/health/` shows Django status
3. **Verify environment**: Check env vars are set correctly
4. **Database connection**: Ensure DATABASE_URL is correct
5. **Static files**: Verify CSS files exist in image

## 🔄 **Automation Ideas**

Future improvements:
- [ ] GitHub Actions for automated deployments
- [ ] Pre-commit hooks for static file builds  
- [ ] Docker health checks
- [ ] Automated backup scripts
- [ ] Monitoring and alerting setup

---

**Follow this checklist and you'll never have deployment issues again!** ✅