modern-django-starter/DOKPLOY.md

# 🚀 Dokploy Deployment Guide - Django Template

Complete step-by-step guide to deploy your Django template on Dokploy using Docker Compose (2025).

## 📋 Prerequisites

- **Dokploy server** with admin access
- **Domain name** pointed to your server (A record)
- **GitHub repository**: `https://github.com/thecyberlearn/modern-django-starter`

## 🌐 Step 1: Domain Setup

### Configure DNS Record
```
Type: A
Name: app (or subdomain of your choice)
Value: YOUR_DOKPLOY_SERVER_IP
TTL: 3600
```

**Example**: `app.yourdomain.com` → `123.456.789.123`

## 🏗️ Step 2: Create Project in Dokploy

1. **Login** to your Dokploy dashboard
2. Click **"Create Project"**
3. **Fill Project Details**:
   - **Project Name**: `django-template` (or your preferred name)
   - **Description**: `Modern Django template with Tailwind CSS`
4. Click **"Create Project"**

## ⚙️ Step 3: Create Service - Compose

1. **Inside your project**, click **"Create Service"**
2. **Select Service Type**: **"Compose"**
3. **Fill the "Create Compose" form**:

### 📝 Form Fields to Fill:

- **Name**: `Django Template` *(or your preferred service name)*
- **App Name**: `django-template-prod` *(unique identifier for this service)*
- **Compose Type**: `Docker Compose` *(keep as selected)*
- **Description**: `Modern Django template with Tailwind CSS, authentication, and PostgreSQL database`

4. **Click "Create"** to proceed to configuration

## 📂 Step 4: Configure Repository Source

### Fill Repository Configuration Form:

- **Provider**: `GitHub`
- **Repository**: `https://github.com/thecyberlearn/modern-django-starter`
- **Branch**: `main`
- **Compose Path**: `./docker-compose.dokploy.yml`

Click **"Save"** to save repository settings.

## 🔧 Step 5: Configure Raw Docker Compose (Alternative Method)

If you prefer to paste the compose file directly:

1. Go to **"General"** → **"Raw"** tab
2. **Paste this Docker Compose configuration**:

```yaml
services:
  web:
    build:
      context: .
      target: production
    command: >
      sh -c "chmod +x /app/entrypoint.sh &&
             /app/entrypoint.sh &&
             gunicorn --bind 0.0.0.0:8000 --workers 3 django_project.wsgi:application"      
    volumes:
      - "../files/static:/app/staticfiles"
      - "../files/media:/app/media"
    expose:
      - 8000
    env_file:
      - .env
    depends_on:
      - db
      - redis
    environment:
      - DJANGO_SETTINGS_MODULE=django_project.settings.production
    networks:
      - dokploy-network
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.django-app-UNIQUE.rule=Host(\`your-domain.com\`)"
      - "traefik.http.routers.django-app-UNIQUE.entrypoints=websecure"
      - "traefik.http.routers.django-app-UNIQUE.tls.certResolver=letsencrypt"
      - "traefik.http.services.django-app-UNIQUE.loadbalancer.server.port=8000"

  db:
    image: postgres:15-alpine
    volumes:
      - "../files/postgres_data:/var/lib/postgresql/data/"
    environment:
      - POSTGRES_DB=${DB_NAME:-django_db}
      - POSTGRES_USER=${DB_USER:-django_user}
      - POSTGRES_PASSWORD=${DB_PASSWORD:-django_password}
    networks:
      - dokploy-network

  redis:
    image: redis:7-alpine
    volumes:
      - "../files/redis_data:/data"
    networks:
      - dokploy-network

networks:
  dokploy-network:
    external: true
```

3. **Replace `UNIQUE` and `your-domain.com`** with your values
4. Click **"Save"**

## 🌍 Step 6: Environment Variables

1. Go to **"Environment"** tab
2. **Add these environment variables**:

```env
# Django Configuration
SECRET_KEY=your-very-long-random-secret-key-generate-new-one
DEBUG=False
ALLOWED_HOSTS=app.yourdomain.com,yourdomain.com
DJANGO_SETTINGS_MODULE=django_project.settings.production

# Database Configuration
DB_NAME=django_db
DB_USER=django_user
DB_PASSWORD=super_secure_password_123
DB_HOST=db
DB_PORT=5432

# Email Configuration (Production)
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-gmail-app-password
DEFAULT_FROM_EMAIL=noreply@yourdomain.com

# Social Authentication (Optional)
GOOGLE_OAUTH2_CLIENT_ID=your-google-client-id
GOOGLE_OAUTH2_CLIENT_SECRET=your-google-client-secret

# Security Settings
SECURE_SSL_REDIRECT=True
```

3. Click **"Save Environment"**

## 🌐 Step 7: Domain Configuration

### Method A: Using Traefik Labels (Recommended)
Your domain is already configured in the Docker Compose labels. Just update:
- Replace `your-domain.com` with your actual domain (e.g., `app.yourdomain.com`)
- Replace `django-app-UNIQUE` with a unique identifier (e.g., `django-app-prod`)

### Method B: Using Dokploy Domain Tab
1. Go to **"Domains"** tab
2. Click **"Add Domain"**
3. **Fill Domain Form**:
   - **Domain**: `app.yourdomain.com`
   - **Service**: `web`
   - **Port**: `8000`
4. Click **"Save"**

## 🚀 Step 8: Deploy Application

1. Go to **"General"** tab
2. Click **"Deploy"** button
3. **Monitor deployment** in the **"Deployments"** tab
4. Wait for build to complete (5-10 minutes)

## ⚡ Step 9: Post-Deployment Setup

After successful deployment, access the **web service console**:

1. Go to **"Services"** → **"web"** → **"Terminal"**
2. **Run these commands**:

```bash
# Run database migrations
python manage.py migrate

# Create default user groups (admin, staff, user)
python manage.py create_groups

# Create your admin user
python manage.py createsuperuser
# Enter email and password when prompted

# Build Tailwind CSS for production
python manage.py tailwind build

# Collect static files
python manage.py collectstatic --noinput
```

## ✅ Step 10: Verify Deployment

1. **Visit your domain**: `https://app.yourdomain.com`
2. **Check SSL certificate**: Should show green padlock
3. **Test authentication**: Register/login functionality
4. **Admin access**: `https://app.yourdomain.com/admin/`

## 🔧 Important Configuration Notes

### **Architecture Overview (2025 Best Practices)**
This Django template follows industry-standard Docker patterns:
- **Django/Gunicorn**: Handles dynamic content only
- **Nginx**: Serves static/media files directly (6000+ req/sec performance)
- **Non-root user**: Application runs as `django` user for security
- **Shared volumes**: Static files accessible to both Django and Nginx
- **Clean separation**: Database, cache, web app as separate services

### **Unique Identifiers**
- Replace `django-app-UNIQUE` with a unique name like `django-app-prod-2025`
- This prevents conflicts with other services

### **Volume Persistence**
- All data is stored in `../files/` directory
- Survives deployments and container restarts
- Located on Dokploy server filesystem

### **Environment Variables**
- **SECRET_KEY**: Generate new one for production
- **DB_PASSWORD**: Use strong, unique password
- **ALLOWED_HOSTS**: Include all domains/subdomains
- **EMAIL_HOST_PASSWORD**: Use Gmail app password, not regular password

### **SSL Certificate**
- Automatically generated by Let's Encrypt via Traefik
- May take 1-2 minutes after deployment
- Requires valid domain pointing to server

## 🆘 Troubleshooting

### **Build Fails**
```bash
# Check deployment logs in Dokploy
# Common issues:
# - Missing environment variables
# - Invalid Docker Compose syntax
# - Network connectivity issues
```

### **Django Logging Error (FileNotFoundError)**
If you see error: `FileNotFoundError: [Errno 2] No such file or directory: '/var/log/django/django.log'`

**Solution**: This is already fixed in the latest version. The production settings now use console logging only, which is Docker-friendly and works with Dokploy's log viewing system.

### **Static Files Permission Error**
If you see error: `PermissionError: [Errno 13] Permission denied: '/app/staticfiles/js'`

**Solution**: Following 2025 Docker best practices:
- Directories created in Dockerfile with proper ownership (`chown -R django:django /app`)
- Application runs as non-root user throughout (security best practice)
- Docker volumes provide persistent storage for static/media files
- Nginx serves static files directly for optimal performance

### **Domain Not Accessible**
```bash
# Check DNS propagation
nslookup app.yourdomain.com

# Verify Traefik labels
# Ensure unique router names
# Check domain configuration in Dokploy
```

### **Database Connection Error**
```bash
# Verify environment variables match
# Check PostgreSQL service is running
# Verify network connectivity between services
```

### **Static Files Not Loading**
```bash
# Access web service terminal
python manage.py collectstatic --noinput

# Check volume mounts
# Verify static file paths
```

### **SSL Certificate Issues**
```bash
# Wait 2-3 minutes after deployment
# Check domain DNS resolution
# Verify Let's Encrypt rate limits not exceeded
# Check Traefik logs in Dokploy
```

## 🎯 Production Checklist

- [ ] **Domain** correctly pointed to server
- [ ] **Environment variables** all configured
- [ ] **Database** migrations completed
- [ ] **Admin user** created
- [ ] **SSL certificate** working
- [ ] **Static files** loading correctly
- [ ] **Email** configuration tested
- [ ] **Social auth** configured (if needed)
- [ ] **Monitoring** set up
- [ ] **Backups** configured

## 🔄 Updating Application

To update your deployed application:

1. **Push changes** to GitHub repository
2. In Dokploy, go to **"General"** tab
3. Click **"Deploy"** button
4. Monitor deployment progress
5. **Run any new migrations** if needed:
   ```bash
   python manage.py migrate
   python manage.py collectstatic --noinput
   ```

## 📊 Monitoring and Logs

- **Application Logs**: Available in Dokploy **"Logs"** tab
- **Service Monitoring**: Individual service status and metrics
- **Deployment History**: Last 10 deployments with detailed logs
- **Resource Usage**: CPU, memory, and disk usage monitoring

---

**🎉 Congratulations!** Your Django template is now deployed on Dokploy with professional-grade configuration including SSL, persistent data, and automated deployments!

**Need help?** Check the deployment logs in Dokploy or review the troubleshooting section above.