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

Environment Variables Reference

Variable	Description	Required	Default
SECRET_KEY	Django secret key	Yes	-
DEBUG	Debug mode	Yes	False
ALLOWED_HOSTS	Allowed hostnames	Yes	-
DB_NAME	Database name	Yes	django_db
DB_USER	Database user	Yes	django_user
DB_PASSWORD	Database password	Yes	-
DB_HOST	Database host	Yes	postgres
DB_PORT	Database port	Yes	5432
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	-

🐳 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
   

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

Getting Help

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

---

Happy deploying! 🚀