modern-django-starter/QUICKSTART.md

# 🚀 Quick Start Guide - New Django Project

Get your Django project running in **5 minutes** with authentication, modern UI, and database setup.

## ⚡ Prerequisites

- **Docker** and **Docker Compose** installed
- **Git** installed
- **10 minutes** of your time

## 🎯 5-Minute Setup

### 1. Clone & Setup
```bash
# Clone this template to your new project
git clone <your-repo-url> my-awesome-project
cd my-awesome-project

# Copy environment configuration
cp .env.example .env
```

### 2. Configure Environment (Optional)
Edit `.env` file if needed, or keep defaults for local development:
```env
SECRET_KEY=your-secret-key-here-make-it-long-and-random
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1,0.0.0.0
# Database will use Docker PostgreSQL by default
```

### 3. Start Everything
```bash
# Build and start all services (database, redis, web app)
docker-compose up --build

# Wait for "Starting development server at http://0.0.0.0:8000/"
```

### 4. Setup Database & Users
Open a **new terminal** and run:
```bash
# Run database migrations
docker-compose exec web python manage.py migrate

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

# Create your admin account
docker-compose exec web python manage.py createsuperuser
# Follow prompts: enter email and password
```

### 5. Start Tailwind Development
In **another terminal**:
```bash
# Start Tailwind hot-reloading for UI development
docker-compose exec web python manage.py tailwind start
```

## 🎉 You're Ready!

- **Web App**: http://localhost:8001
- **Admin Panel**: http://localhost:8001/admin
- **Hot Reloading**: CSS updates automatically when you edit templates

## ✅ What You Get Out of the Box

- ✨ **Modern UI** - Tailwind CSS with professional black/white theme
- 🔐 **Complete Auth** - Registration, login, email verification, password reset
- 👥 **User Roles** - Admin, staff, user groups with permissions
- 🌐 **Social Login** - Google OAuth (configure in settings)
- 🐳 **Docker Ready** - Development and production configurations
- 📱 **Responsive** - Mobile-first design

## 🔧 First Customizations

### 1. Update Project Name
```bash
# Update these files with your project name:
# - django_project/settings/base.py (change app name)
# - templates/base.html (update title and branding)
# - README.md (project description)
```

### 2. Customize Styling
```bash
# Edit templates with Tailwind classes:
# - templates/home.html (homepage content)
# - templates/base.html (navigation and footer)
# - theme/static_src/src/styles.css (custom CSS)
```

### 3. Add Your Business Logic
```bash
# Create new Django app
docker-compose exec web python manage.py startapp myapp

# Add to INSTALLED_APPS in django_project/settings/base.py
# Create models, views, templates in apps/myapp/
```

## 🚀 Common Next Steps

### Add New Django App
```bash
docker-compose exec web python manage.py startapp blog
# Add 'apps.blog' to INSTALLED_APPS
```

### Install New Python Package
```bash
# Add to requirements/base.txt
# Rebuild container: docker-compose up --build
```

### Configure External Database
```bash
# For production, use managed databases like Neon or Supabase
# Update .env with DATABASE_URL instead of individual DB_* vars
DATABASE_URL=postgresql://user:pass@host/database?sslmode=require
```

### Setup Email (Production)
```bash
# Configure in .env:
EMAIL_HOST=smtp.gmail.com
EMAIL_HOST_USER=your-email@gmail.com
EMAIL_HOST_PASSWORD=your-app-password
```

### Social Authentication
```bash
# Get Google OAuth credentials from Google Cloud Console
# Update .env:
GOOGLE_OAUTH2_CLIENT_ID=your-client-id
GOOGLE_OAUTH2_CLIENT_SECRET=your-secret
```

## 🛠️ Useful Commands

```bash
# View logs
docker-compose logs web

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

# Create superuser (admin)
docker-compose exec web python manage.py createsuperuser

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

# Collect static files (production)
docker-compose exec web python manage.py collectstatic

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

# Access database
docker-compose exec db psql -U django_user -d django_db
```

## 🆘 Troubleshooting

### CSS Not Loading?
```bash
# Restart Tailwind development server
docker-compose exec web python manage.py tailwind start
```

### Database Issues?
```bash
# Reset database (WARNING: deletes all data)
docker-compose down -v
docker-compose up --build
# Run migrations again
```

### Permission Denied?
```bash
# Fix file permissions
sudo chown -R $USER:$USER .
```

### Port Already in Use?
```bash
# Change port in docker-compose.yml:
# ports: "8002:8000"  # Use port 8002 instead
```

## 📚 Full Documentation

- **Complete Setup**: See [README.md](README.md)
- **Deployment Guide**: See [DEPLOYMENT.md](DEPLOYMENT.md)
- **Django Docs**: https://docs.djangoproject.com/
- **Tailwind CSS**: https://tailwindcss.com/docs

## 🎯 Project Structure
```
my-project/
├── apps/                 # Your Django applications
├── django_project/       # Main project settings
├── templates/           # HTML templates
├── theme/              # Tailwind CSS theme
├── static/             # Static files
├── requirements/       # Python dependencies
├── docker-compose.yml  # Development setup
└── .env               # Environment variables
```

---

**Need help?** Check the full README.md or open an issue in the repository.

**Ready to deploy?** See DEPLOYMENT.md for production deployment guides.