mirror of
https://github.com/thecyberlearn/modern-django-starter.git
synced 2026-08-18 08:52:55 +00:00
Add comprehensive Dokploy deployment configuration and guide
## 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 <noreply@anthropic.com>
This commit is contained in:
Django Template
parent
f5e6d0d560
commit
07dd7b0e47
311
DOKPLOY.md
Normal file
311
DOKPLOY.md
Normal file
@ -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.
|
||||
51
docker-compose.dokploy.yml
Normal file
51
docker-compose.dokploy.yml
Normal file
@ -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
|
||||
Loading…
Reference in New Issue
Block a user