diff --git a/.env.example b/.env.example index ba1971d..defdd00 100644 --- a/.env.example +++ b/.env.example @@ -4,11 +4,31 @@ DEBUG=True ALLOWED_HOSTS=localhost,127.0.0.1,0.0.0.0 # Database Configuration +# Option 1: Individual variables (for Docker Compose/local development) DB_NAME=django_db DB_USER=django_user DB_PASSWORD=django_password DB_HOST=db DB_PORT=5432 +DB_SSLMODE=prefer + +# Option 2: DATABASE_URL (for external services like Neon, Heroku, Railway, etc.) +# Uncomment and use ONE of the following examples: + +# Neon (https://neon.tech) +# DATABASE_URL=postgresql://user:password@ep-xxx.us-east-1.aws.neon.tech/database?sslmode=require + +# Supabase (https://supabase.com) +# DATABASE_URL=postgresql://postgres:password@db.xxx.supabase.co:5432/postgres?sslmode=require + +# Railway (https://railway.app) +# DATABASE_URL=postgresql://postgres:password@containers-us-west-xxx.railway.app:5432/railway + +# Heroku Postgres +# DATABASE_URL=postgres://user:password@host:5432/database + +# Amazon RDS +# DATABASE_URL=postgresql://user:password@your-rds-instance.amazonaws.com:5432/database # Email Configuration (for production) EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index 5ad0b09..b415016 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -71,6 +71,9 @@ Dokploy is a modern deployment platform that makes it easy to deploy application 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 ``` @@ -82,6 +85,44 @@ Dokploy is a modern deployment platform that makes it easy to deploy application - 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 | @@ -89,11 +130,13 @@ Dokploy is a modern deployment platform that makes it easy to deploy application | `SECRET_KEY` | Django secret key | Yes | - | | `DEBUG` | Debug mode | Yes | False | | `ALLOWED_HOSTS` | Allowed hostnames | Yes | - | -| `DB_NAME` | Database name | Yes | django_db | -| `DB_USER` | Database user | Yes | django_user | -| `DB_PASSWORD` | Database password | Yes | - | -| `DB_HOST` | Database host | Yes | postgres | -| `DB_PORT` | Database port | Yes | 5432 | +| `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 | - | @@ -103,6 +146,8 @@ Dokploy is a modern deployment platform that makes it easy to deploy application | `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 @@ -227,6 +272,64 @@ Consider adding: 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:** @@ -261,6 +364,18 @@ Consider adding: - 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 diff --git a/Dockerfile b/Dockerfile index 1644b69..14acd6f 100644 --- a/Dockerfile +++ b/Dockerfile @@ -9,6 +9,9 @@ RUN apt-get update \ build-essential \ libpq-dev \ gettext \ + curl \ + && curl -fsSL https://deb.nodesource.com/setup_18.x | bash - \ + && apt-get install -y nodejs \ && rm -rf /var/lib/apt/lists/* WORKDIR /app diff --git a/README.md b/README.md index 1ef92a5..f4bea1f 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# Django Boilerplate +# Django Template -A production-ready Django boilerplate with built-in authentication, social login, role-based permissions, and Docker support. +A production-ready Django template with built-in authentication, social login, role-based permissions, modern UI with Tailwind CSS, and Docker support. ## ✨ Features @@ -28,10 +28,13 @@ A production-ready Django boilerplate with built-in authentication, social login - Nginx reverse proxy - Gunicorn WSGI server -- 🎨 **Modern Frontend** - - Bootstrap 5 integration - - Responsive design - - Clean, professional UI +- 🎨 **Modern Frontend with Tailwind CSS** + - Tailwind CSS v3.4+ integration with django-tailwind + - Hot-reloading during development + - Responsive design with mobile-first approach + - Professional black/white theme + - Modern card layouts and components + - Optimized CSS builds for production - ⚙️ **Environment Management** - Separate settings for development/production @@ -121,10 +124,73 @@ docker-compose exec web python manage.py createsuperuser docker-compose exec web python manage.py create_superuser --email admin@example.com --password admin123 ``` -### 7. Access the Application +### 7. Start Tailwind Development Server -- **Web Application**: http://localhost:8000 -- **Django Admin**: http://localhost:8000/admin/ +```bash +# In a separate terminal, start Tailwind's watch mode for hot reloading +docker-compose exec web python manage.py tailwind start +``` + +### 8. Access the Application + +- **Web Application**: http://localhost:8001 (or http://localhost:8000) +- **Django Admin**: http://localhost:8001/admin/ + +## 🎨 Tailwind CSS Development + +### Hot Reloading Setup + +The project uses `django-tailwind` for seamless Tailwind CSS integration: + +1. **Development Mode:** + ```bash + # Start Tailwind watch mode (automatically rebuilds CSS on changes) + docker-compose exec web python manage.py tailwind start + ``` + +2. **Building for Production:** + ```bash + # Build minified CSS for production + docker-compose exec web python manage.py tailwind build + ``` + +3. **Customizing Styles:** + - Edit templates with Tailwind utility classes + - Modify `theme/static_src/src/styles.css` for custom CSS + - Update `theme/static_src/tailwind.config.js` for configuration + +### Theme Structure + +``` +theme/ +├── static_src/ # Tailwind source files +│ ├── src/ +│ │ └── styles.css # Main Tailwind CSS file +│ ├── tailwind.config.js # Tailwind configuration +│ ├── package.json # Node.js dependencies +│ └── node_modules/ # Node.js packages +├── static/ +│ └── css/ +│ └── dist/ +│ └── styles.css # Generated CSS file +└── templates/ # Theme templates +``` + +### Adding Custom Components + +Create reusable Tailwind components in your templates: + +```html + +
Hello, {{ user.full_name|default:user.email }}!
-Hello, {{ user.full_name|default:user.email }}!
Email: {{ user.email }}
-Name: {{ user.full_name|default:"Not set" }}
-Username: {{ user.username }}
-Member since: {{ user.date_joined|date:"M d, Y" }}
-Email verified: +
Email: {{ user.email }}
+Name: {{ user.full_name|default:"Not set" }}
+Username: {{ user.username }}
+Member since: {{ user.date_joined|date:"M d, Y" }}
++ Email verified: {% if user.is_verified %} - Yes + Yes {% else %} - No + No {% endif %}
- Edit Profile +No roles assigned
+No roles assigned
{% endif %} - -{{ user.email }}
+{{ user.email }}
- {% if user.profile.bio %} -Bio: {{ user.profile.bio }}
- {% endif %} - - {% if user.profile.location %} -Location: {{ user.profile.location }}
- {% endif %} - - {% if user.profile.birth_date %} -Birth Date: {{ user.profile.birth_date }}
- {% endif %} - - {% if user.profile.phone_number %} -Phone: {{ user.profile.phone_number }}
- {% endif %} - -Member since: {{ user.date_joined|date:"M d, Y" }}
+{{ user.profile.bio }}
++ Location: {{ user.profile.location }} +
+ {% endif %} + + {% if user.profile.birth_date %} ++ Birth Date: {{ user.profile.birth_date }} +
+ {% endif %} + + {% if user.profile.phone_number %} ++ Phone: {{ user.profile.phone_number }} +
+ {% endif %} + ++ Member since: {{ user.date_joined|date:"M d, Y" }} +
+Email verified: - {% if user.is_verified %} - Yes - {% else %} - No - {% endif %} -
-Account type: {{ user.groups.first.name|default:"User"|title }}
+{{ user.groups.first.name|default:"User"|title }}
+