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.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:

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:

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:

#!/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

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! ✅