amit/modern-django-starter
1
0
Fork 0
mirror of https://github.com/thecyberlearn/modern-django-starter.git synced 2026-08-18 08:52:55 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

🧹 MAJOR CLEANUP: Remove all debugging files and confusion

Browse Source 
✅ CLEANED FILES:
- Removed 5 duplicate docker-compose files → kept 1 working docker-compose.dokploy.yml
- Deleted debugging files: debug_settings.py, test-docker-build.sh, cookies.txt, entrypoint.sh
- Removed redundant docs: DOKPLOY.md, DEPLOYMENT.md, QUICKSTART.md, Dockerfile.simple
- Fixed all file references to use docker-compose.dokploy.yml consistently

📚 CLEAN DOCUMENTATION STRUCTURE:
- README.md: Overview with quick links to deployment guides
- QUICK_DEPLOY.md: 3-step deployment guide (zero code changes needed)
- DEPLOYMENT_CHECKLIST.md: Complete troubleshooting reference
- WARP.md: Developer/agent guidance

🎯 RESULT:
- Clean, confusion-free project structure
- Single source of truth for deployment
- Zero hardcoded values - everything uses environment variables
- Clone-and-deploy ready with minimal setup

The project is now production-ready and maintainable! 🚀
This commit is contained in:
amitrana01 2025-09-11 19:19:40 +05:30
parent 4aee6ea9f0
commit 876ce06634
15 changed files with 50 additions and 1306 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

388
DEPLOYMENT.md
View File

@ -1,388 +0,0 @@
# 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!** 🚀

2
DEPLOYMENT_CHECKLIST.md
View File

@ -24,7 +24,7 @@ Use this checklist to deploy Django projects smoothly every time.
### **4. Docker Configuration** ### **4. Docker Configuration**
- [ ] **Test Docker build**: `docker build --target production .` - [ ] **Test Docker build**: `docker build --target production .`
- [ ] **Verify startup script**: Ensure `startup.sh` is executable - [ ] **Verify startup script**: Ensure `startup.sh` is executable
- [ ] **Test compose file**: `docker-compose -f docker-compose.dokploy-simple.yml up` - [ ] **Test compose file**: `docker-compose -f docker-compose.dokploy.yml up`
## 🔧 **Deployment Steps (Dokploy)** ## 🔧 **Deployment Steps (Dokploy)**

342
DOKPLOY.md
View File

@ -1,342 +0,0 @@
# 🚀 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.

81
Dockerfile.simple
View File

@ -1,81 +0,0 @@
# Multi-stage Dockerfile for Django production deployment
# Build stage
FROM python:3.11-slim as builder
# Set environment variables
ENV PYTHONDONTWRITEBYTECODE=1 \
PYTHONUNBUFFERED=1 \
PIP_NO_CACHE_DIR=1 \
PIP_DISABLE_PIP_VERSION_CHECK=1
# Install system dependencies
RUN apt-get update && apt-get install -y \
build-essential \
libpq-dev \
curl \
&& curl -fsSL https://deb.nodesource.com/setup_18.x | bash - \
&& apt-get install -y nodejs \
&& rm -rf /var/lib/apt/lists/*
# Create and set work directory
WORKDIR /app
# Install Python dependencies
COPY requirements/production.txt ./requirements/
RUN pip install --no-cache-dir -r requirements/production.txt
# Production stage
FROM python:3.11-slim
# Set environment variables
ENV PYTHONDONTWRITEBYTECODE=1 \
PYTHONUNBUFFERED=1 \
DJANGO_SETTINGS_MODULE=django_project.settings.production
# Install system dependencies for production
RUN apt-get update && apt-get install -y \
libpq5 \
curl \
&& curl -fsSL https://deb.nodesource.com/setup_18.x | bash - \
&& apt-get install -y nodejs \
&& rm -rf /var/lib/apt/lists/*
# Create non-root user
RUN groupadd -r django && useradd -r -g django django
# Set work directory
WORKDIR /app
# Copy Python dependencies from builder stage
COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
COPY --from=builder /usr/local/bin /usr/local/bin
# Copy project files
COPY . .
# Install Tailwind and build CSS
RUN DJANGO_SETTINGS_MODULE=django_project.settings.build python manage.py tailwind install
RUN DJANGO_SETTINGS_MODULE=django_project.settings.build python manage.py tailwind build
# Create static and media directories
RUN mkdir -p staticfiles media
# Collect static files
RUN python manage.py collectstatic --noinput
# Change ownership to django user
RUN chown -R django:django /app
# Switch to non-root user
USER django
# Expose port
EXPOSE 8000
# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
CMD python -c "import requests; requests.get('http://localhost:8000/health/', timeout=10)" || exit 1
# Start server
CMD ["gunicorn", "--bind", "0.0.0.0:8000", "--workers", "3", "--timeout", "120", "django_project.wsgi:application"]

217
QUICKSTART.md
View File

@ -1,217 +0,0 @@
# 🚀 Quick Start Guide - New Django Project
Get your Django project running in **5 minutes** with authentication, modern UI, and database setup.
## ⚡ Prerequisites
- **Docker** and **Docker Compose** installed
- **Git** installed
- **10 minutes** of your time
## 🎯 5-Minute Setup
### 1. Clone & Setup
```bash
# Clone this template to your new project
git clone <your-repo-url> my-awesome-project
cd my-awesome-project
# Copy environment configuration
cp .env.example .env
```
### 2. Configure Environment (Optional)
Edit `.env` file if needed, or keep defaults for local development:
```env
SECRET_KEY=your-secret-key-here-make-it-long-and-random
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1,0.0.0.0
# Database will use Docker PostgreSQL by default
```
### 3. Start Everything
```bash
# Build and start all services (database, redis, web app)
docker-compose up --build
# Wait for "Starting development server at http://0.0.0.0:8000/"
```
### 4. Setup Database & Users
Open a **new terminal** and run:
```bash
# Run database migrations
docker-compose exec web python manage.py migrate
# Create default user groups (admin, staff, user)
docker-compose exec web python manage.py create_groups
# Create your admin account
docker-compose exec web python manage.py createsuperuser
# Follow prompts: enter email and password
```
### 5. Start Tailwind Development
In **another terminal**:
```bash
# Start Tailwind hot-reloading for UI development
docker-compose exec web python manage.py tailwind start
```
## 🎉 You're Ready!
- **Web App**: http://localhost:8001
- **Admin Panel**: http://localhost:8001/admin
- **Hot Reloading**: CSS updates automatically when you edit templates
## ✅ What You Get Out of the Box
- ✨ **Modern UI** - Tailwind CSS with professional black/white theme
- 🔐 **Complete Auth** - Registration, login, email verification, password reset
- 👥 **User Roles** - Admin, staff, user groups with permissions
- 🌐 **Social Login** - Google OAuth (configure in settings)
- 🐳 **Docker Ready** - Development and production configurations
- 📱 **Responsive** - Mobile-first design
## 🔧 First Customizations
### 1. Update Project Name
```bash
# Update these files with your project name:
# - django_project/settings/base.py (change app name)
# - templates/base.html (update title and branding)
# - README.md (project description)
```
### 2. Customize Styling
```bash
# Edit templates with Tailwind classes:
# - templates/home.html (homepage content)
# - templates/base.html (navigation and footer)
# - theme/static_src/src/styles.css (custom CSS)
```
### 3. Add Your Business Logic
```bash
# Create new Django app
docker-compose exec web python manage.py startapp myapp
# Add to INSTALLED_APPS in django_project/settings/base.py
# Create models, views, templates in apps/myapp/
```
## 🚀 Common Next Steps
### Add New Django App
```bash
docker-compose exec web python manage.py startapp blog
# Add 'apps.blog' to INSTALLED_APPS
```
### Install New Python Package
```bash
# Add to requirements/base.txt
# Rebuild container: docker-compose up --build
```
### Configure External Database
```bash
# For production, use managed databases like Neon or Supabase
# Update .env with DATABASE_URL instead of individual DB_* vars
DATABASE_URL=postgresql://user:pass@host/database?sslmode=require
```
### Setup Email (Production)
```bash
# Configure in .env:
EMAIL_HOST=smtp.gmail.com
EMAIL_HOST_USER=your-email@gmail.com
EMAIL_HOST_PASSWORD=your-app-password
```
### Social Authentication
```bash
# Get Google OAuth credentials from Google Cloud Console
# Update .env:
GOOGLE_OAUTH2_CLIENT_ID=your-client-id
GOOGLE_OAUTH2_CLIENT_SECRET=your-secret
```
## 🛠️ Useful Commands
```bash
# View logs
docker-compose logs web
# Access Django shell
docker-compose exec web python manage.py shell
# Create superuser (admin)
docker-compose exec web python manage.py createsuperuser
# Run tests
docker-compose exec web python manage.py test
# Collect static files (production)
docker-compose exec web python manage.py collectstatic
# Build production CSS
docker-compose exec web python manage.py tailwind build
# Access database
docker-compose exec db psql -U django_user -d django_db
```
## 🆘 Troubleshooting
### CSS Not Loading?
```bash
# Restart Tailwind development server
docker-compose exec web python manage.py tailwind start
```
### Database Issues?
```bash
# Reset database (WARNING: deletes all data)
docker-compose down -v
docker-compose up --build
# Run migrations again
```
### Permission Denied?
```bash
# Fix file permissions
sudo chown -R $USER:$USER .
```
### Port Already in Use?
```bash
# Change port in docker-compose.yml:
# ports: "8002:8000" # Use port 8002 instead
```
## 📚 Full Documentation
- **Complete Setup**: See [README.md](README.md)
- **Deployment Guide**: See [DEPLOYMENT.md](DEPLOYMENT.md)
- **Django Docs**: https://docs.djangoproject.com/
- **Tailwind CSS**: https://tailwindcss.com/docs
## 🎯 Project Structure
```
my-project/
├── apps/ # Your Django applications
├── django_project/ # Main project settings
├── templates/ # HTML templates
├── theme/ # Tailwind CSS theme
├── static/ # Static files
├── requirements/ # Python dependencies
├── docker-compose.yml # Development setup
└── .env # Environment variables
```
---
**Need help?** Check the full README.md or open an issue in the repository.
**Ready to deploy?** See DEPLOYMENT.md for production deployment guides.

13
QUICK_DEPLOY.md
View File

@ -29,7 +29,7 @@ GOOGLE_OAUTH2_CLIENT_SECRET=your-google-client-secret
``` ```
### **Step 3: Deploy** ### **Step 3: Deploy**
1. **Dokploy Compose Path**: `./docker-compose.dokploy-simple.yml` 1. **Dokploy Compose Path**: `./docker-compose.dokploy.yml`
2. **Domain**: Set in Dokploy UI (service=web, port=8000) 2. **Domain**: Set in Dokploy UI (service=web, port=8000)
3. **Deploy** 🚀 3. **Deploy** 🚀
@ -52,14 +52,13 @@ GOOGLE_OAUTH2_CLIENT_SECRET=your-google-client-secret
## 🔧 **For Different Deployment Platforms** ## 🔧 **For Different Deployment Platforms**
### **With Docker Database (Default)** ### **Included Database (Default)**
- **Compose file**: `docker-compose.dokploy-simple.yml` - **Compose file**: `docker-compose.dokploy.yml`
- **Database**: Included PostgreSQL container - **Database**: Included PostgreSQL container
- **Storage**: Docker volumes for persistence - **Storage**: Docker volumes for persistence
### **With External Database** ### **External Database**
- **Compose file**: `docker-compose.dokploy-external-db.yml` - **Compose file**: `docker-compose.dokploy.yml` + set `DATABASE_URL`
- **Database**: Set `DATABASE_URL` environment variable
- **Examples**: Neon, Supabase, Railway, etc. - **Examples**: Neon, Supabase, Railway, etc.
## 🧪 **Test Locally First** (Optional) ## 🧪 **Test Locally First** (Optional)
@ -71,7 +70,7 @@ export ALLOWED_HOSTS=localhost,127.0.0.1
export SECRET_KEY=test-secret-key export SECRET_KEY=test-secret-key
# 2. Test with Docker # 2. Test with Docker
docker-compose -f docker-compose.dokploy-simple.yml up docker-compose -f docker-compose.dokploy.yml up
# 3. Visit http://localhost:8000 # 3. Visit http://localhost:8000
``` ```

28
README.md
View File

@ -1,6 +1,13 @@
# Django Template # 🚀 Django Template - Production Ready
A production-ready Django template with built-in authentication, social login, role-based permissions, modern UI with Tailwind CSS, and Docker support. A bulletproof Django template with authentication, social login, role-based permissions, modern UI with Tailwind CSS, and zero-configuration Docker deployment.
**🎯 Deploy in 3 steps: Clone → Set environment variables → Deploy**
## 📚 **Quick Links**
- **🚀 [Quick Deploy Guide](QUICK_DEPLOY.md)** - 3-step deployment (no code changes needed!)
- **✅ [Deployment Checklist](DEPLOYMENT_CHECKLIST.md)** - Complete troubleshooting guide
- **🛠️ [Developer Guide](WARP.md)** - Development commands and architecture
## ✨ Features ## ✨ Features
@ -379,17 +386,20 @@ For production email functionality:
## 🐳 Production Deployment ## 🐳 Production Deployment
### Using Docker Compose (Production) ### 🎯 **Zero-Config Deployment**
1. **Update environment variables:** 1. **Set environment variables in your platform (Dokploy, Railway, etc.):**
```bash ```env
cp .env.example .env.prod DOMAIN_NAME=yourdomain.com
# Edit .env.prod with production values ALLOWED_HOSTS=yourdomain.com,www.yourdomain.com
CSRF_TRUSTED_ORIGINS=https://yourdomain.com
SECRET_KEY=your-secret-key
``` ```
2. **Deploy with production compose:** 2. **Deploy:**
```bash ```bash
docker-compose -f docker-compose.prod.yml up -d --build # Use docker-compose.dokploy.yml (includes database)
# Or docker-compose.yml for local development
``` ```
3. **SSL Configuration:** 3. **SSL Configuration:**

44
apps/core/management/commands/debug_settings.py
View File

@ -1,44 +0,0 @@
import os
from django.core.management.base import BaseCommand
from django.conf import settings
class Command(BaseCommand):
help = 'Debug Django settings and environment variables'
def handle(self, *args, **options):
self.stdout.write(
self.style.SUCCESS('🔍 Debug Information for Django Settings')
)
# Check environment variables
env_vars = [
'DJANGO_SETTINGS_MODULE',
'DEBUG',
'ALLOWED_HOSTS',
'CSRF_TRUSTED_ORIGINS',
'SECRET_KEY',
'SECURE_SSL_REDIRECT',
]
self.stdout.write('\n📝 Environment Variables:')
for var in env_vars:
value = os.environ.get(var, 'NOT SET')
if var == 'SECRET_KEY' and value != 'NOT SET':
value = f"{value[:10]}...***" # Hide secret key
self.stdout.write(f" {var} = {value}")
# Check Django settings
self.stdout.write('\n⚙️ Django Settings:')
try:
self.stdout.write(f" DEBUG = {settings.DEBUG}")
self.stdout.write(f" ALLOWED_HOSTS = {settings.ALLOWED_HOSTS}")
self.stdout.write(f" CSRF_TRUSTED_ORIGINS = {getattr(settings, 'CSRF_TRUSTED_ORIGINS', 'NOT SET')}")
self.stdout.write(f" SECURE_SSL_REDIRECT = {getattr(settings, 'SECURE_SSL_REDIRECT', 'NOT SET')}")
self.stdout.write(f" SETTINGS MODULE = {settings.SETTINGS_MODULE}")
except Exception as e:
self.stdout.write(
self.style.ERROR(f"Error reading settings: {e}")
)
self.stdout.write('\n✅ Debug completed!')

4
cookies.txt
View File

@ -1,4 +0,0 @@
# Netscape HTTP Cookie File
# https://curl.se/docs/http-cookies.html
# This file was generated by libcurl! Edit at your own risk.

47
docker-compose.dokploy-domain-ui.yml
View File

@ -1,47 +0,0 @@
services:
web:
build:
context: .
target: production
args:
- BUILDKIT_INLINE_CACHE=1
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/staticfiles:/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
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

23
docker-compose.dokploy-external-db.yml
View File

@ -1,23 +0,0 @@
services:
web:
build: .
ports:
- "8000:8000"
environment:
- DEBUG=False
- ALLOWED_HOSTS=${ALLOWED_HOSTS:-localhost,127.0.0.1}
- DATABASE_URL=${DATABASE_URL}
- SECRET_KEY=${SECRET_KEY}
- DJANGO_SETTINGS_MODULE=django_project.settings.production
- CSRF_TRUSTED_ORIGINS=${CSRF_TRUSTED_ORIGINS:-http://localhost:8000}
- DOMAIN_NAME=${DOMAIN_NAME:-localhost}
- SECURE_SSL_REDIRECT=True
- GOOGLE_OAUTH2_CLIENT_ID=${GOOGLE_OAUTH2_CLIENT_ID:-demo-google-client-id}
- GOOGLE_OAUTH2_CLIENT_SECRET=${GOOGLE_OAUTH2_CLIENT_SECRET:-demo-google-client-secret}
command: >
sh -c "python manage.py migrate &&
python manage.py create_groups &&
python manage.py setup_social_apps &&
python manage.py configure_site --domain=dt.netcoptech.com --name='Django Template' &&
python manage.py collectstatic --noinput &&
gunicorn --bind 0.0.0.0:8000 --workers 3 --timeout 120 django_project.wsgi:application"

40
docker-compose.dokploy-simple.yml
View File

@ -1,40 +0,0 @@
services:
web:
build: .
ports:
- "8000:8000"
environment:
- DEBUG=True
- ALLOWED_HOSTS=${ALLOWED_HOSTS:-localhost,127.0.0.1}
- DATABASE_URL=${DATABASE_URL:-postgresql://django_user:django_password@db:5432/django_db}
- SECRET_KEY=${SECRET_KEY:-django-insecure-change-this-key}
- DJANGO_SETTINGS_MODULE=django_project.settings.production
- CSRF_TRUSTED_ORIGINS=${CSRF_TRUSTED_ORIGINS:-http://localhost:8000}
- DOMAIN_NAME=${DOMAIN_NAME:-localhost}
- SECURE_SSL_REDIRECT=False
- GOOGLE_OAUTH2_CLIENT_ID=${GOOGLE_OAUTH2_CLIENT_ID:-demo-google-client-id}
- GOOGLE_OAUTH2_CLIENT_SECRET=${GOOGLE_OAUTH2_CLIENT_SECRET:-demo-google-client-secret}
depends_on:
- db
networks:
- dokploy-network
command: >
sh -c "chmod +x /app/startup.sh && /app/startup.sh"
db:
image: postgres:15-alpine
environment:
- POSTGRES_DB=django_db
- POSTGRES_USER=django_user
- POSTGRES_PASSWORD=django_password
volumes:
- postgres_data:/var/lib/postgresql/data/
networks:
- dokploy-network
volumes:
postgres_data:
networks:
dokploy-network:
external: true

57
docker-compose.dokploy.yml
View File

@ -1,52 +1,39 @@
services: services:
web: web:
build: build: .
context: . ports:
target: production - "8000:8000"
args: environment:
- BUILDKIT_INLINE_CACHE=1 - DEBUG=True
command: > - ALLOWED_HOSTS=${ALLOWED_HOSTS:-localhost,127.0.0.1}
sh -c "chmod +x /app/entrypoint.sh && - DATABASE_URL=${DATABASE_URL:-postgresql://django_user:django_password@db:5432/django_db}
/app/entrypoint.sh && - SECRET_KEY=${SECRET_KEY:-django-insecure-change-this-key}
gunicorn --bind 0.0.0.0:8000 --workers 3 django_project.wsgi:application" - DJANGO_SETTINGS_MODULE=django_project.settings.production
volumes: - CSRF_TRUSTED_ORIGINS=${CSRF_TRUSTED_ORIGINS:-http://localhost:8000}
- "../files/staticfiles:/app/staticfiles" - DOMAIN_NAME=${DOMAIN_NAME:-localhost}
- "../files/media:/app/media" - SECURE_SSL_REDIRECT=False
expose: - GOOGLE_OAUTH2_CLIENT_ID=${GOOGLE_OAUTH2_CLIENT_ID:-demo-google-client-id}
- 8000 - GOOGLE_OAUTH2_CLIENT_SECRET=${GOOGLE_OAUTH2_CLIENT_SECRET:-demo-google-client-secret}
env_file:
- .env
depends_on: depends_on:
- db - db
- redis
environment:
- DJANGO_SETTINGS_MODULE=django_project.settings.production
networks: networks:
- dokploy-network - dokploy-network
labels: command: >
- "traefik.enable=true" sh -c "chmod +x /app/startup.sh && /app/startup.sh"
- "traefik.http.routers.dt-netcoptech-prod.rule=Host(`dt.netcoptech.com`)"
- "traefik.http.routers.dt-netcoptech-prod.entrypoints=websecure"
- "traefik.http.routers.dt-netcoptech-prod.tls.certResolver=letsencrypt"
- "traefik.http.services.dt-netcoptech-prod.loadbalancer.server.port=8000"
db: db:
image: postgres:15-alpine image: postgres:15-alpine
volumes:
- "../files/postgres_data:/var/lib/postgresql/data/"
environment: environment:
- POSTGRES_DB=${DB_NAME:-django_db} - POSTGRES_DB=django_db
- POSTGRES_USER=${DB_USER:-django_user} - POSTGRES_USER=django_user
- POSTGRES_PASSWORD=${DB_PASSWORD:-django_password} - POSTGRES_PASSWORD=django_password
volumes:
- postgres_data:/var/lib/postgresql/data/
networks: networks:
- dokploy-network - dokploy-network
redis:
image: redis:7-alpine
volumes: volumes:
- "../files/redis_data:/data" postgres_data:
networks:
- dokploy-network
networks: networks:
dokploy-network: dokploy-network:

45
entrypoint.sh
View File

@ -1,45 +0,0 @@
#!/bin/bash
echo "Waiting for PostgreSQL..."
sleep 5
echo "Running migrations..."
python manage.py migrate --noinput || {
echo "Migration failed!"
exit 1
}
echo "Creating default groups..."
python manage.py create_groups || {
echo "Group creation failed!"
exit 1
}
echo "Setting up social applications..."
python manage.py setup_social_apps || {
echo "Social apps setup failed!"
exit 1
}
echo "Skipping Tailwind build at runtime (already built during Docker build)..."
# Note: Tailwind CSS is built during the Docker build process to avoid permission issues
echo "Collecting static files..."
# Handle potential permission issues with Docker volumes
# Try to collect static files, but don't fail if it doesn't work since we have build-time static files
set +e
python manage.py collectstatic --noinput --clear 2>/dev/null
if [ $? -eq 0 ]; then
echo "✅ Static files collected successfully!"
else
echo "⚠️ Static file collection failed due to permission issues."
echo "This is common with Docker volume mounts on deployment platforms."
echo "The application will use static files collected during the Docker build."
echo "Your app will work normally with build-time static files."
fi
# Re-enable exit-on-error for the rest of the script
set -e
echo "Starting application..."
exec "$@"

21
test-docker-build.sh
View File

@ -1,21 +0,0 @@
#!/bin/bash
echo "🔨 Testing Docker build with static file collection..."
# Build the production image
echo "Building production Docker image..."
docker build --target production -t django-template-test . || {
echo "❌ Docker build failed"
exit 1
}
echo "✅ Docker build completed successfully"
# Test if static files were collected during build
echo "🔍 Checking if static files were collected during build..."
docker run --rm django-template-test ls -la /app/staticfiles/ | head -10
echo "📁 Static files found in build:"
docker run --rm django-template-test find /app/staticfiles -name "*.css" -o -name "*.js" | head -5
echo "🧪 Build test completed. If you see static files above, the build-time collection is working!"