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

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

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

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

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

# 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

# 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

# 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

# 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

docker-compose exec web python manage.py startapp blog
# Add 'apps.blog' to INSTALLED_APPS

Install New Python Package

# Add to requirements/base.txt
# Rebuild container: docker-compose up --build

Configure External Database

# 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)

# Configure in .env:
EMAIL_HOST=smtp.gmail.com
EMAIL_HOST_USER=your-email@gmail.com
EMAIL_HOST_PASSWORD=your-app-password

Social Authentication

# 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

# 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?

# Restart Tailwind development server
docker-compose exec web python manage.py tailwind start

Database Issues?

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

Permission Denied?

# Fix file permissions
sudo chown -R $USER:$USER .

Port Already in Use?

# Change port in docker-compose.yml:
# ports: "8002:8000"  # Use port 8002 instead

📚 Full Documentation

• Complete Setup: See README.md
• Deployment Guide: See 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.