modern-django-starter/README.md

Django Boilerplate

A production-ready Django boilerplate with built-in authentication, social login, role-based permissions, 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

  • Bootstrap 5 integration
  • Responsive design
  • Clean, professional UI

• ⚙️ 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. Access the Application

• Web Application: http://localhost:8000
• Django Admin: http://localhost:8000/admin/

🔧 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
   

🌐 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)
├── 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

# 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! 🚀