From f5e6d0d560078519d6fd0d7f019b9ff7950797c5 Mon Sep 17 00:00:00 2001 From: Django Template Date: Thu, 11 Sep 2025 15:24:25 +0530 Subject: [PATCH] Add comprehensive QUICKSTART.md guide for new projects MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This guide enables developers to get started with the Django template in just 5 minutes: ## Features: - **5-Minute Setup Process** - Clone, configure, and run steps - **Copy-Paste Commands** - Ready-to-execute terminal commands - **Essential Customizations** - Project name, styling, business logic - **Developer Commands** - Reference for daily development tasks - **Troubleshooting** - Solutions for common setup issues ## Target Audience: Developers who want to immediately start building without reading extensive documentation first. ## Structure: - Prerequisites and setup steps - Database and user account creation - Tailwind CSS development server setup - First customization checklist - Common next steps and commands - Troubleshooting section This makes the Django template even more accessible for rapid project initialization. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- QUICKSTART.md | 217 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 217 insertions(+) create mode 100644 QUICKSTART.md diff --git a/QUICKSTART.md b/QUICKSTART.md new file mode 100644 index 0000000..761637d --- /dev/null +++ b/QUICKSTART.md @@ -0,0 +1,217 @@ +# 🚀 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 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. \ No newline at end of file