From 07dd7b0e470c76f92f90a2f8011a8d6c471b240f Mon Sep 17 00:00:00 2001 From: Django Template Date: Thu, 11 Sep 2025 15:46:12 +0530 Subject: [PATCH] Add comprehensive Dokploy deployment configuration and guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## New Files Added: - **docker-compose.dokploy.yml** - Dokploy-optimized compose file with: - dokploy-network integration for all services - Traefik labels for SSL and domain routing - Persistent volumes using ../files/ directory - Production-ready Django, PostgreSQL, and Redis configuration - **DOKPLOY.md** - Complete step-by-step deployment guide including: - 10-step deployment process with exact form fields - Domain configuration and DNS setup - Environment variables for production - Post-deployment Django setup commands - Comprehensive troubleshooting section - Production checklist and monitoring guidance ## Key Features: - **Production-ready** configuration with SSL certificates - **Persistent data** storage across deployments - **Detailed troubleshooting** for common issues - **Copy-paste configurations** for immediate use - **Security best practices** implemented This enables one-click deployment of the Django template on any Dokploy server with professional-grade configuration. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- DOKPLOY.md | 311 +++++++++++++++++++++++++++++++++++++ docker-compose.dokploy.yml | 51 ++++++ 2 files changed, 362 insertions(+) create mode 100644 DOKPLOY.md create mode 100644 docker-compose.dokploy.yml diff --git a/DOKPLOY.md b/DOKPLOY.md new file mode 100644 index 0000000..2d10930 --- /dev/null +++ b/DOKPLOY.md @@ -0,0 +1,311 @@ +# 🚀 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. **Choose Compose Type**: **"Docker Compose"** (not Stack) + +## 📂 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 + +### **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 +``` + +### **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. \ No newline at end of file diff --git a/docker-compose.dokploy.yml b/docker-compose.dokploy.yml new file mode 100644 index 0000000..83ba38c --- /dev/null +++ b/docker-compose.dokploy.yml @@ -0,0 +1,51 @@ +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.rule=Host(`your-domain.com`)" + - "traefik.http.routers.django-app.entrypoints=websecure" + - "traefik.http.routers.django-app.tls.certResolver=letsencrypt" + - "traefik.http.services.django-app.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 \ No newline at end of file