modern-django-starter/WARP.md

WARP.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

Project Overview

This is a production-ready Django template with built-in authentication, social login (Google OAuth), role-based permissions, modern UI with Tailwind CSS, and Docker support. The project uses a custom User model with email-based authentication and role management through Django groups.

Development Commands

Initial Setup (Docker)

# Start all services (web, database, redis)
docker-compose up --build

# In separate terminals:
# Run database migrations and setup
docker-compose exec web python manage.py migrate
docker-compose exec web python manage.py create_groups
docker-compose exec web python manage.py createsuperuser

# Start Tailwind CSS development server (hot reloading)
docker-compose exec web python manage.py tailwind start

Development Workflow

# Start development environment
docker-compose up -d

# View logs
docker-compose logs -f web

# Access Django shell
docker-compose exec web python manage.py shell

# Run migrations
docker-compose exec web python manage.py makemigrations
docker-compose exec web python manage.py migrate

# Create new Django app
docker-compose exec web python manage.py startapp myapp
# Remember to add 'apps.myapp' to INSTALLED_APPS in django_project/settings/base.py

Testing & Quality

# Run tests (basic Django test runner)
docker-compose exec web python manage.py test

# Run tests with coverage (if coverage package is added)
docker-compose exec web coverage run --source='.' manage.py test
docker-compose exec web coverage report

Tailwind CSS Development

# Start Tailwind watch mode for CSS hot reloading
docker-compose exec web python manage.py tailwind start

# Build production CSS
docker-compose exec web python manage.py tailwind build

# Install/update Tailwind dependencies
docker-compose exec web python manage.py tailwind install

User Management

# Create user groups (admin, staff, user)
docker-compose exec web python manage.py create_groups

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

# Setup social authentication apps
docker-compose exec web python manage.py setup_social_apps

Production Deployment

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

# Production database operations
docker-compose -f docker-compose.prod.yml exec web python manage.py migrate
docker-compose -f docker-compose.prod.yml exec web python manage.py collectstatic --noinput

Architecture Overview

Project Structure

• django_project/: Main Django project configuration
  • settings/: Environment-specific settings (base.py, development.py, production.py)
  • urls.py: Root URL configuration
• apps/: Django applications following app-per-feature pattern
  • accounts/: Custom user model, authentication, user management
  • core/: Core utilities, views, role-based decorators and mixins
• templates/: Global HTML templates
• static/: Static files (CSS, JS, images)
• theme/: Tailwind CSS integration
  • static_src/: Tailwind source files and Node.js setup
  • static/css/dist/: Generated CSS output

Key Architectural Decisions

Authentication & User Management

• Custom User Model: apps.accounts.User extends AbstractUser with email as username field
• Email-based Authentication: Users authenticate with email instead of username
• Role-based Access Control: Uses Django groups (admin, staff, user) with custom methods:
  • user.has_role(role_name) - Check user role
  • user.assign_role(role_name) - Assign role to user
  • @admin_required and @staff_required decorators for views
  • AdminRequiredMixin and StaffRequiredMixin for class-based views
• Django Allauth Integration: Handles registration, email verification, password reset, and social authentication

Database Configuration

• Flexible Database Setup: Supports both individual environment variables and DATABASE_URL
• External Database Support: Ready for services like Neon, Supabase, Railway
• SSL Support: Configurable SSL mode for secure connections

Frontend & Styling

• Tailwind CSS Integration: Uses django-tailwind for seamless CSS development
• Hot Reloading: CSS automatically rebuilds during development
• Production Optimization: Compressed and minified CSS for production builds

Docker & Deployment

• Multi-stage Dockerfile: Separate development and production builds
• Development Setup: Docker Compose with PostgreSQL, Redis, hot reloading
• Production Ready: Gunicorn, Nginx, SSL support, security best practices

Custom Management Commands

Located in apps/accounts/management/commands/:

• create_groups: Creates default user groups with appropriate permissions
• create_superuser: Creates admin user with default credentials
• setup_social_apps: Configures social authentication providers

Settings Architecture

• base.py: Common settings for all environments
• development.py: Development-specific settings (DEBUG=True, console email backend)
• production.py: Production settings (security, performance optimizations)
• Environment Variables: All sensitive data configured via .env files

Development Guidelines

Adding New Features

1. Create new Django app: docker-compose exec web python manage.py startapp feature_name
2. Add to INSTALLED_APPS in django_project/settings/base.py as apps.feature_name
3. Create models, views, templates following existing patterns
4. Use role-based decorators/mixins for access control
5. Add URL patterns to both app-level and project-level URLs

Database Migrations

• Always create migrations after model changes: python manage.py makemigrations
• Review migration files before applying
• Test migrations on copy of production data when possible

Role-Based Access Control

• Use @login_required decorator for authenticated views
• Use @admin_required or @staff_required for role-specific views
• In templates, use {% if user.has_role:'admin' %} for conditional content
• For class-based views, inherit from AdminRequiredMixin or StaffRequiredMixin

Tailwind CSS Development

• Edit templates with Tailwind utility classes
• Custom CSS goes in theme/static_src/src/styles.css
• Run python manage.py tailwind start for development with hot reloading
• Build for production with python manage.py tailwind build

Environment Configuration

• Development: Copy .env.example to .env
• Production: Use strong SECRET_KEY, set DEBUG=False, configure email settings
• Database: Use DATABASE_URL for external services or individual DB_* variables for Docker

Security Considerations

• Custom User model stores email as primary identifier
• Email verification required for account activation
• Login attempt limiting (5 attempts, 300s timeout)
• SSL support for external database connections
• CSRF and clickjacking protection enabled
• WhiteNoise for secure static file serving

Social Authentication Setup

• Google OAuth: Configure in Google Cloud Console, set GOOGLE_OAUTH2_CLIENT_ID and GOOGLE_OAUTH2_CLIENT_SECRET
• Add more providers by extending SOCIALACCOUNT_PROVIDERS in settings
• Use python manage.py setup_social_apps to configure in Django admin

URLs & Endpoints

• Home: / - Main landing page
• Authentication: /accounts/ - Login, registration, email verification (django-allauth)
• Admin: /admin/ - Django admin interface
• API: Ready for Django REST Framework integration

Common Issues & Solutions

CSS Not Loading

• Ensure Tailwind development server is running: python manage.py tailwind start
• Check that theme app is in INSTALLED_APPS
• Verify static files configuration

Database Connection Issues

• For external databases, ensure SSL mode is correct (require/prefer)
• Check DATABASE_URL format for external services
• Verify PostgreSQL service is running in Docker

Email Configuration

• Development: Uses console backend by default
• Production: Configure SMTP settings in environment variables
• Test email functionality with password reset flow

Role Assignment

• Use management command: python manage.py create_groups
• Assign roles programmatically: user.assign_role('admin')
• Check roles in templates: user.has_role:'staff'

Dokploy Deployment Issues

• Static Files Permission Error: If you see "Permission denied" errors during collectstatic:
  • This occurs when Docker volumes have different ownership than the container user
  • The project includes multiple fallback mechanisms in the entrypoint script
  • Static files are collected during Docker build as a backup
  • If collectstatic fails at runtime, the application will use build-time static files
• Build Settings: The project includes django_project/settings/build.py for static collection during Docker build
• Volume Permissions: Dokploy mounts volumes that may have host-system ownership