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

```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. Start Tailwind Development Server

```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
<!-- 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:**
   ```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
   ```

## 🗄️ 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](https://neon.tech)** - Serverless PostgreSQL with branching
- **[Supabase](https://supabase.com)** - Open source Firebase alternative
- **[Railway](https://railway.app)** - Deploy from GitHub in seconds
- **[ElephantSQL](https://www.elephantsql.com)** - PostgreSQL as a Service
- **[Amazon RDS](https://aws.amazon.com/rds)** - AWS managed databases
- **[Google Cloud SQL](https://cloud.google.com/sql)** - Google Cloud databases
- **Any PostgreSQL-compatible service**

### Configuration Methods

#### Method 1: DATABASE_URL (Recommended)

Set a single environment variable:

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

**Neon Example:**
```env
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:**
```env
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:

```env
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](https://neon.tech)
2. **Copy your connection string** from the Neon dashboard
3. **Add to your .env file:**
   ```env
   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](https://supabase.com)
2. **Go to Settings > Database**
3. **Copy the connection string and add to .env:**
   ```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:

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

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

```yaml
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](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)
├── 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

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

# 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

```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!** 🚀