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:

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:

# 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:

# 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

# 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

# Check DNS propagation
nslookup app.yourdomain.com

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

Database Connection Error

# Verify environment variables match
# Check PostgreSQL service is running
# Verify network connectivity between services

Static Files Not Loading

# Access web service terminal
python manage.py collectstatic --noinput

# Check volume mounts
# Verify static file paths

SSL Certificate Issues

# 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:

   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.