modern-django-starter/README.md

Django Template

A production-ready Django template with built-in authentication, social login, role-based permissions, modern UI with Tailwind CSS, and Docker support.

✨ Features

• 🔐 Complete Authentication System

  • Email/password registration and login
  • Email verification required for account activation
  • Password reset workflows
  • Django Allauth integration

• 🌐 Social Authentication

  • Google OAuth2 integration
  • Facebook OAuth2 integration
  • Easy to extend for other providers

• 👥 Role-Based Access Control

  • User groups: admin, staff, user
  • Permission-based access control
  • Custom decorators and mixins for role checking

• 🐳 Docker & Production Ready

  • Multi-stage Dockerfile
  • Docker Compose for development and production
  • PostgreSQL database
  • Redis for caching
  • Nginx reverse proxy
  • Gunicorn WSGI server

• 🎨 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
  • Environment variables for sensitive data
  • Comprehensive configuration

🚀 Quick Start

Prerequisites

• Docker and Docker Compose
• Git

1. Clone the Repository

git clone https://github.com/yourusername/django-template.git
cd django-template

2. Environment Configuration

cp .env.example .env

Edit the .env file with your configuration:

# Django Configuration
SECRET_KEY=your-very-long-and-random-secret-key
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1,0.0.0.0

# Database Configuration
DB_NAME=django_db
DB_USER=django_user
DB_PASSWORD=secure_password
DB_HOST=db
DB_PORT=5432

# Email Configuration (for 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-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

3. Build and Run with Docker

# Build and start the services
docker-compose up --build

# Or run in detached mode
docker-compose up -d --build

4. Run Database Migrations

docker-compose exec web python manage.py migrate

5. Create Default User Groups

docker-compose exec web python manage.py create_groups

6. Create a Superuser

# Interactive creation
docker-compose exec web python manage.py createsuperuser

# Or use management command with defaults
docker-compose exec web python manage.py create_superuser --email admin@example.com --password admin123

7. Start Tailwind Development Server

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

   # Start Tailwind watch mode (automatically rebuilds CSS on changes)
   docker-compose exec web python manage.py tailwind start
   

2. Building for Production:

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

<!-- Card component example -->
<div class="bg-white rounded-lg shadow-lg border border-gray-200">
    <div class="px-6 py-4 border-b border-gray-200">
        <h2 class="text-xl font-semibold text-gray-900">Card Title</h2>
    </div>
    <div class="px-6 py-6">
        <!-- Card content -->
    </div>
</div>

🔧 Development Setup

Local Development (without Docker)

1. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\\Scripts\\activate
   

2. Install dependencies:

   pip install -r requirements/development.txt
   

3. Set up local database:

   # Install and start PostgreSQL
   # Create database and user as configured in .env
   

4. Run migrations:

   python manage.py migrate
   python manage.py create_groups
   python manage.py createsuperuser
   

5. Start development server:

   python manage.py runserver
   

🗄️ Third-Party Database Services

The application supports external PostgreSQL services like Neon, Supabase, Railway, and others. You can use either individual environment variables or a single DATABASE_URL.

Supported Services

• Neon - Serverless PostgreSQL with branching
• Supabase - Open source Firebase alternative
• Railway - Deploy from GitHub in seconds
• ElephantSQL - PostgreSQL as a Service
• Amazon RDS - AWS managed databases
• Google Cloud SQL - Google Cloud databases
• Any PostgreSQL-compatible service

Configuration Methods

Method 1: DATABASE_URL (Recommended)

Set a single environment variable:

DATABASE_URL=postgresql://user:password@host:port/database?sslmode=require

Neon Example:

DATABASE_URL=postgresql://neondb_owner:npg_ZO9W1DxrTwJu@ep-solitary-water-a1ucgv2p-pooler.ap-southeast-1.aws.neon.tech/neondb?sslmode=require&channel_binding=require

Supabase Example:

DATABASE_URL=postgresql://postgres:your-password@db.xxx.supabase.co:5432/postgres?sslmode=require

Method 2: Individual Variables

For more control, use separate environment variables:

DB_NAME=your_database_name
DB_USER=your_username
DB_PASSWORD=your_password
DB_HOST=your-host.amazonaws.com
DB_PORT=5432
DB_SSLMODE=require  # For secure connections

Quick Setup Examples

Neon Database

1. Create a Neon project at neon.tech
2. Copy your connection string from the Neon dashboard
3. Add to your .env file:

   DATABASE_URL=postgresql://user:pass@ep-xxx.us-east-1.aws.neon.tech/dbname?sslmode=require
   

Supabase Database

1. Create a Supabase project at supabase.com
2. Go to Settings > Database
3. Copy the connection string and add to .env:

   DATABASE_URL=postgresql://postgres:your-password@db.xxx.supabase.co:5432/postgres?sslmode=require
   

Railway Database

1. Deploy to Railway from GitHub
2. Add PostgreSQL plugin
3. Railway automatically sets DATABASE_URL

SSL and Security

For production databases, always use SSL:

# Enable SSL for external databases
DB_SSLMODE=require        # or 'prefer' for flexible connections
DATABASE_URL=postgresql://user:pass@host/db?sslmode=require

Migration Commands

After configuring your external database:

# Run migrations
python manage.py migrate

# Create user groups
python manage.py create_groups

# Create admin user
python manage.py createsuperuser

Docker with External Database

When using external databases with Docker, update your docker-compose.yml:

services:
  web:
    # ... other config
    environment:
      - DATABASE_URL=postgresql://user:pass@external-host/db?sslmode=require
    # Remove the 'db' service when using external database

🌐 Social Authentication Setup

Google OAuth2

1. Go to Google Cloud Console
2. Create a new project or select existing
3. Enable Google+ API
4. Create OAuth2 credentials
5. Add authorized redirect URIs:
   • http://localhost:8000/accounts/google/login/callback/
   • https://yourdomain.com/accounts/google/login/callback/
6. Update .env with your client ID and secret

Facebook OAuth2

1. Go to Facebook Developers
2. Create a new app
3. Add Facebook Login product
4. Configure Valid OAuth Redirect URIs:
   • http://localhost:8000/accounts/facebook/login/callback/
   • https://yourdomain.com/accounts/facebook/login/callback/
5. Update .env with your app ID and secret

📧 Email Configuration

For production email functionality:

1. Gmail Setup:

   EMAIL_HOST=smtp.gmail.com
   EMAIL_PORT=587
   EMAIL_USE_TLS=True
   EMAIL_HOST_USER=your-gmail@gmail.com
   EMAIL_HOST_PASSWORD=your-app-password
   

2. Generate App Password:

   • Enable 2FA on your Gmail account
   • Generate an app-specific password
   • Use this password in EMAIL_HOST_PASSWORD

🐳 Production Deployment

Using Docker Compose (Production)

1. Update environment variables:

   cp .env.example .env.prod
   # Edit .env.prod with production values
   

2. Deploy with production compose:

   docker-compose -f docker-compose.prod.yml up -d --build
   

3. SSL Configuration:

   • Place SSL certificates in ssl/ directory
   • Update nginx.prod.conf with your domain
   • Certificates should be named cert.pem and key.pem

Environment Variables for Production

DEBUG=False
ALLOWED_HOSTS=yourdomain.com,www.yourdomain.com
SECURE_SSL_REDIRECT=True
SECRET_KEY=generate-a-new-secure-secret-key

# Database
DB_PASSWORD=use-a-strong-database-password

# Email
EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
# Configure with your email provider

# Social Auth
# Configure with production callback URLs

📁 Project Structure

django-template/
├── django_project/          # Main Django project
│   ├── settings/           # Environment-specific settings
│   ├── urls.py             # Main URL configuration
│   └── wsgi.py             # WSGI application
├── apps/                   # Django applications
│   ├── accounts/           # User authentication & profiles
│   └── core/               # Core application logic
├── templates/              # HTML templates
├── static/                 # Static files (CSS, JS, images)
├── theme/                  # Tailwind CSS theme
│   ├── static_src/         # Tailwind source files
│   │   ├── src/           # CSS source files
│   │   ├── tailwind.config.js
│   │   └── package.json   # Node.js dependencies
│   ├── static/            # Generated CSS files
│   └── templates/         # Theme-specific templates
├── requirements/           # Python dependencies
├── Dockerfile              # Docker configuration
├── docker-compose.yml      # Development Docker Compose
├── docker-compose.prod.yml # Production Docker Compose
├── nginx.conf              # Nginx configuration
└── entrypoint.sh           # Docker entrypoint script

🔐 User Roles & Permissions

Default User Groups

• admin: Full administrative access
• staff: Limited administrative access
• user: Basic user permissions

Usage in Views

from apps.core.views import admin_required, staff_required

@login_required
@admin_required
def admin_only_view(request):
    return render(request, 'admin_only.html')

@login_required
@staff_required
def staff_view(request):
    return render(request, 'staff.html')

Usage in Templates

{% if user.has_role:'admin' %}
    <a href="{% url 'admin_dashboard' %}">Admin Panel</a>
{% endif %}

🛠️ Management Commands

# Create default user groups
python manage.py create_groups

# Create superuser with admin role
python manage.py create_superuser --email admin@example.com --password admin123

# Tailwind CSS commands
python manage.py tailwind install    # Install Tailwind CSS dependencies
python manage.py tailwind start     # Start development server with hot reload
python manage.py tailwind build     # Build production CSS
python manage.py tailwind check     # Check for Tailwind updates

# Standard Django commands
python manage.py migrate
python manage.py collectstatic
python manage.py createsuperuser

🧪 Testing

# Run tests
docker-compose exec web python manage.py test

# With coverage
docker-compose exec web coverage run --source='.' manage.py test
docker-compose exec web coverage report

📚 API Documentation

The project is ready for API development. Consider adding:

• Django REST Framework
• API documentation with drf-yasg
• Authentication tokens
• Throttling and permissions

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Create an issue for bug reports or feature requests
• Check the Django documentation: https://docs.djangoproject.com/
• Django Allauth documentation: https://django-allauth.readthedocs.io/

🎉 What's Next?

Consider adding these features:

• API with Django REST Framework
• Celery for background tasks
• Monitoring with Sentry
• CI/CD pipeline
• Advanced user profiles
• Multi-tenant support
• Internationalization (i18n)

---

Happy coding! 🚀