modern-django-starter/DEPLOYMENT.md

Deployment Guide

This guide covers how to deploy the Django Template application using various platforms including Dokploy.

🚀 Dokploy Deployment

Dokploy is a modern deployment platform that makes it easy to deploy applications with Docker.

Prerequisites

1. A Dokploy account and server
2. A GitHub repository with your code
3. Domain name (optional but recommended)

Quick Deploy

1. Fork this repository to your GitHub account

2. Connect to Dokploy:

   • Log in to your Dokploy dashboard
   • Click "New Application"
   • Connect your GitHub repository

3. Configure Environment Variables:

   SECRET_KEY=your-very-long-random-secret-key
   DEBUG=False
   ALLOWED_HOSTS=your-domain.com,www.your-domain.com
   
   # Database (Dokploy will provide these)
   DB_NAME=django_db
   DB_USER=django_user
   DB_PASSWORD=secure_password
   DB_HOST=postgres
   DB_PORT=5432
   
   # Email Configuration
   EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
   EMAIL_HOST=smtp.gmail.com
   EMAIL_PORT=587
   EMAIL_USE_TLS=True
   EMAIL_HOST_USER=your-email@gmail.com
   EMAIL_HOST_PASSWORD=your-app-password
   DEFAULT_FROM_EMAIL=noreply@your-domain.com
   
   # Social Authentication
   GOOGLE_OAUTH2_CLIENT_ID=your-google-client-id
   GOOGLE_OAUTH2_CLIENT_SECRET=your-google-client-secret
   FACEBOOK_APP_ID=your-facebook-app-id
   FACEBOOK_APP_SECRET=your-facebook-app-secret
   
   # Security
   SECURE_SSL_REDIRECT=True
   

4. Configure Database:

   • Add a PostgreSQL database service
   • Use PostgreSQL 15
   • Database name: django_db
   • Username: django_user

5. Deploy:

   • Click "Deploy"
   • Dokploy will build and deploy your application automatically

Post-Deployment Steps

1. Run initial setup:

   # Access your application console in Dokploy
   python manage.py migrate
   python manage.py create_groups
   python manage.py createsuperuser
   
   # Build Tailwind CSS for production
   python manage.py tailwind build
   python manage.py collectstatic --noinput
   

2. Configure Domain:

   • Add your domain in Dokploy dashboard
   • Configure SSL certificate (Let's Encrypt recommended)

3. Set up Social Authentication:

   • Configure Google OAuth2 callback URL: https://your-domain.com/accounts/google/login/callback/
   • Configure Facebook OAuth2 callback URL: https://your-domain.com/accounts/facebook/login/callback/

🗄️ External Database Services

Instead of setting up your own PostgreSQL instance, you can use managed database services:

Neon (Recommended)

1. Create account at neon.tech
2. Create a database in your Neon dashboard
3. Copy connection string from the dashboard
4. Set environment variable:

   DATABASE_URL=postgresql://user:password@ep-xxx.us-east-1.aws.neon.tech/database?sslmode=require
   

Supabase

1. Create project at supabase.com
2. Go to Settings > Database
3. Use connection pooler URL for production:

   DATABASE_URL=postgresql://postgres:password@db.xxx.supabase.co:6543/postgres?sslmode=require
   

Railway

1. Connect GitHub repo to Railway
2. Add PostgreSQL service
3. Railway sets DATABASE_URL automatically

Amazon RDS

1. Create RDS PostgreSQL instance
2. Configure security groups for your application
3. Set DATABASE_URL with RDS endpoint:

   DATABASE_URL=postgresql://user:password@your-rds.amazonaws.com:5432/database
   

Environment Variables Reference

Variable	Description	Required	Default
SECRET_KEY	Django secret key	Yes	-
DEBUG	Debug mode	Yes	False
ALLOWED_HOSTS	Allowed hostnames	Yes	-
DATABASE_URL	Full database URL	No*	-
DB_NAME	Database name	No*	django_db
DB_USER	Database user	No*	django_user
DB_PASSWORD	Database password	No*	-
DB_HOST	Database host	No*	postgres
DB_PORT	Database port	No*	5432
DB_SSLMODE	SSL mode for database	No	prefer
EMAIL_HOST	SMTP host	No	localhost
EMAIL_PORT	SMTP port	No	587
EMAIL_HOST_USER	SMTP username	No	-
EMAIL_HOST_PASSWORD	SMTP password	No	-
GOOGLE_OAUTH2_CLIENT_ID	Google OAuth2 ID	No	-
GOOGLE_OAUTH2_CLIENT_SECRET	Google OAuth2 secret	No	-
FACEBOOK_APP_ID	Facebook app ID	No	-
FACEBOOK_APP_SECRET	Facebook app secret	No	-

Note: Either DATABASE_URL OR the individual DB_* variables are required, not both.

🐳 Docker Deployment

Production Docker Compose

# Create production environment file
cp .env.example .env.prod

# Edit .env.prod with production values
nano .env.prod

# Deploy with production compose
docker-compose -f docker-compose.prod.yml up -d --build

Manual Docker Deployment

# Build production image
docker build --target production -t django-template:latest .

# Run with environment variables
docker run -d \
  --name django-app \
  -p 80:8000 \
  --env-file .env.prod \
  django-template:latest

☁️ Cloud Platform Deployment

Heroku

1. Prepare for Heroku:

   # Create Procfile
   echo "web: gunicorn django_project.wsgi --bind 0.0.0.0:\$PORT" > Procfile
   
   # Create runtime.txt
   echo "python-3.11.0" > runtime.txt
   

2. Deploy to Heroku:

   heroku create your-app-name
   heroku addons:create heroku-postgresql:mini
   heroku config:set SECRET_KEY=your-secret-key
   heroku config:set DEBUG=False
   git push heroku main
   heroku run python manage.py migrate
   heroku run python manage.py create_groups
   heroku run python manage.py createsuperuser
   

Railway

1. Connect GitHub repository to Railway
2. Add PostgreSQL database
3. Configure environment variables
4. Deploy automatically

DigitalOcean App Platform

1. Create new app from GitHub
2. Add managed database (PostgreSQL)
3. Configure environment variables
4. Deploy

🔒 Security Checklist

Before deploying to production:

• Set DEBUG=False
• Use a strong, unique SECRET_KEY
• Configure ALLOWED_HOSTS properly
• Set up SSL/TLS certificate
• Enable SECURE_SSL_REDIRECT=True
• Configure proper database credentials
• Set up email backend for notifications
• Configure social authentication with production URLs
• Set up monitoring and logging
• Configure backup strategy for database
• Review and update all default passwords

📊 Monitoring

Health Checks

The application provides a health check endpoint:

• URL: / (returns 200 if healthy)
• Database connectivity check included

Logging

Logs are configured for production in settings/production.py:

• Application logs: /var/log/django/django.log
• Console output for container logs

Metrics

Consider adding:

• Application Performance Monitoring (APM)
• Database monitoring
• Error tracking (Sentry is pre-configured)

🔄 Updates and Maintenance

Updating the Application

1. Pull latest changes:

   git pull origin main
   

2. Rebuild and redeploy:

   docker-compose -f docker-compose.prod.yml up -d --build
   

3. Run migrations if needed:

   docker-compose -f docker-compose.prod.yml exec web python manage.py migrate
   

4. Rebuild Tailwind CSS:

   docker-compose -f docker-compose.prod.yml exec web python manage.py tailwind build
   docker-compose -f docker-compose.prod.yml exec web python manage.py collectstatic --noinput
   

🎨 Tailwind CSS Production Considerations

Building CSS for Production

The project uses django-tailwind which requires Node.js to build CSS files:

1. Ensure Node.js is available in production:

   # Dockerfile already includes Node.js installation
   RUN curl -fsSL https://deb.nodesource.com/setup_18.x | bash - \
       && apt-get install -y nodejs
   

2. Build process in CI/CD:

   # Install dependencies
   python manage.py tailwind install
   
   # Build production CSS
   python manage.py tailwind build
   
   # Collect static files
   python manage.py collectstatic --noinput
   

3. CSS Optimization:

   • Production builds are automatically minified
   • Unused CSS is purged based on template scanning
   • CSS files are versioned for cache busting

Environment Variables

Add these to your production environment:

# Tailwind CSS
TAILWIND_APP_NAME=theme
NODE_ENV=production

Static Files Structure

After deployment, verify this structure:

/app/static/
├── css/
│   └── dist/
│       └── styles.css      # Built Tailwind CSS
├── js/
└── ...

Backup Strategy

1. Database backup:

   docker-compose -f docker-compose.prod.yml exec db pg_dump -U django_user django_db > backup.sql
   

2. Media files backup:

   docker-compose -f docker-compose.prod.yml exec web tar -czf media_backup.tar.gz /app/media
   

🆘 Troubleshooting

Common Issues

1. 500 Internal Server Error:

   • Check DEBUG=False and ALLOWED_HOSTS
   • Verify database connection
   • Check application logs

2. Static files not loading:

   • Run python manage.py collectstatic
   • Check STATIC_URL and STATIC_ROOT settings

3. Social login not working:

   • Verify callback URLs in provider settings
   • Check client ID and secret configuration

4. Email not sending:

   • Verify SMTP settings
   • Check firewall/security group settings
   • Test email backend configuration

5. Tailwind CSS not loading:

   • Verify Node.js is installed: node --version
   • Check if CSS was built: ls -la static/css/dist/
   • Rebuild CSS: python manage.py tailwind build
   • Ensure static files are collected: python manage.py collectstatic

6. Styling looks broken:

   • Check browser developer tools for CSS loading errors
   • Verify CSS file exists and is accessible
   • Clear browser cache and hard reload
   • Check for console errors

Getting Help

• Check the application logs
• Review the GitHub Issues
• Consult the Django documentation
• Check provider-specific documentation (Dokploy, Heroku, etc.)

---

Happy deploying! 🚀