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

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

### 2. Environment Configuration

```bash
cp .env.example .env
```

Edit the `.env` file with your configuration:

```env
# 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

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

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

### 4. Run Database Migrations

```bash
docker-compose exec web python manage.py migrate
```

### 5. Create Default User Groups

```bash
docker-compose exec web python manage.py create_groups
```

### 6. Create a Superuser

```bash
# 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:**
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\\Scripts\\activate
   ```

2. **Install dependencies:**
   ```bash
   pip install -r requirements/development.txt
   ```

3. **Set up local database:**
   ```bash
   # Install and start PostgreSQL
   # Create database and user as configured in .env
   ```

4. **Run migrations:**
   ```bash
   python manage.py migrate
   python manage.py create_groups
   python manage.py createsuperuser
   ```

5. **Start development server:**
   ```bash
   python manage.py runserver
   ```

## 🌐 Social Authentication Setup

### Google OAuth2

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
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](https://developers.facebook.com/)
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:**
   ```env
   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:**
   ```bash
   cp .env.example .env.prod
   # Edit .env.prod with production values
   ```

2. **Deploy with production compose:**
   ```bash
   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

```env
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

```python
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

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

## 🛠️ Management Commands

```bash
# 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

```bash
# 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](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!** 🚀