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:**
   ```env
   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:**
   ```bash
   # 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

```bash
# 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

```bash
# 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:**
   ```bash
   # 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:**
   ```bash
   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:**
   ```bash
   git pull origin main
   ```

2. **Rebuild and redeploy:**
   ```bash
   docker-compose -f docker-compose.prod.yml up -d --build
   ```

3. **Run migrations if needed:**
   ```bash
   docker-compose -f docker-compose.prod.yml exec web python manage.py migrate
   ```

### Backup Strategy

1. **Database backup:**
   ```bash
   docker-compose -f docker-compose.prod.yml exec db pg_dump -U django_user django_db > backup.sql
   ```

2. **Media files backup:**
   ```bash
   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!** 🚀