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
   
   # 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](https://neon.tech)
2. **Create a database** in your Neon dashboard
3. **Copy connection string** from the dashboard
4. **Set environment variable:**
   ```env
   DATABASE_URL=postgresql://user:password@ep-xxx.us-east-1.aws.neon.tech/database?sslmode=require
   ```

### Supabase

1. **Create project** at [supabase.com](https://supabase.com)
2. **Go to Settings > Database**
3. **Use connection pooler URL for production:**
   ```env
   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:**
   ```env
   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

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

4. **Rebuild Tailwind CSS:**
   ```bash
   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
   # 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:**
   ```bash
   # 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:

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

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!** 🚀