145 lines
5.3 KiB
Markdown
145 lines
5.3 KiB
Markdown
# Django Setup Skill (HTTPS Development)
|
|
|
|
**For HTTPS-only Django projects using mkcert SSL certificates.**
|
|
|
|
## Skill Overview
|
|
|
|
This skill sets up Django projects specifically for **HTTPS local development**, which is required for:
|
|
- WebAuthn/Passkeys (MFA)
|
|
- Secure cookies
|
|
- Service workers
|
|
- Modern browser APIs
|
|
|
|
## Key Features
|
|
|
|
- ✅ **Automatic Python version selection** - Uses highest available 3.8-3.13, installs 3.13 if none found
|
|
- ✅ **HTTPS by default** - Integrated mkcert setup
|
|
- ✅ **Core dependencies** - Django, python-dotenv, djangorestframework, django-cors-headers; adds `uvicorn[standard]` for SSL serving
|
|
- ✅ **Uvicorn ASGI server** - With SSL support
|
|
- ✅ **Manual, guided setup** - No automation scripts, full control
|
|
|
|
## Progressive Disclosure Structure
|
|
|
|
```
|
|
django-setup/
|
|
├── SKILL.md # ⭐ Core skill (HTTPS-focused)
|
|
├── README.md # This file
|
|
│
|
|
├── platform-https/ # 🔒 mkcert + Uvicorn setup per OS
|
|
│ ├── mkcert-https-setup-macos.md
|
|
│ ├── mkcert-https-setup-linux.md
|
|
│ └── mkcert-https-setup-windows.md
|
|
│
|
|
├── platform-install/ # 📦 Platform-specific Python installation
|
|
│ ├── macos.md
|
|
│ ├── linux-ubuntu.md
|
|
│ ├── linux-fedora.md
|
|
│ └── windows.md
|
|
│
|
|
├── troubleshooting/ # 🔧 Problem-solving guides
|
|
│ ├── venv-issues.md
|
|
│ ├── pip-problems.md
|
|
│ └── django-errors.md
|
|
│
|
|
└── examples/ # 📋 Templates
|
|
└── .gitignore-template
|
|
```
|
|
|
|
## What's Different from Standard Django Setup?
|
|
|
|
| Standard Django | This Skill |
|
|
|----------------|------------|
|
|
| HTTP only (port 8000) | HTTPS with mkcert |
|
|
| `python manage.py runserver` | `./run.sh` / `run.bat` (Uvicorn with SSL) |
|
|
| No SSL certificates | SSL certs in `certs/` |
|
|
| Optional HTTPS | HTTPS required |
|
|
| Any dependencies | Focused: Django, dotenv, DRF, django-cors-headers + uvicorn |
|
|
|
|
## Quick Setup Flow
|
|
|
|
1. **Check/install Python 3.8-3.13** (uses highest, installs 3.13 if needed)
|
|
2. **Create venv** with selected Python version
|
|
3. **Install core dependencies** (Django, python-dotenv, djangorestframework, django-cors-headers)
|
|
4. **Create Django project** (`django-admin startproject backend .`)
|
|
5. **Set up mkcert HTTPS + Uvicorn** (platform-https guides install `uvicorn[standard]`, generate certs, create run script)
|
|
6. **Configure settings.py for CORS/CSRF** (adds corsheaders middleware & allowed origins)
|
|
7. **Add health + CSRF helper endpoints** (`api/health`, `api/csrf`)
|
|
8. **Run migrations** (`python manage.py migrate`)
|
|
9. **Optional VS Code launch config** (`.vscode/launch.json`)
|
|
10. **Test with HTTPS** (`./run.sh` or `run.bat` → `https://localhost:8000`)
|
|
|
|
## Why These Dependencies?
|
|
|
|
Authentication packages (allauth, etc.) are **intentionally excluded** and should be added later via the `django-allauth-config` skill to keep the base setup lean. `django-cors-headers` is included because the skill configures CORS/CSRF for a typical HTTPS frontend, and `uvicorn[standard]` is used to serve Django over SSL in development.
|
|
|
|
**Core dependencies:**
|
|
```bash
|
|
pip install Django python-dotenv djangorestframework django-cors-headers
|
|
```
|
|
|
|
**HTTPS server:**
|
|
```bash
|
|
pip install 'uvicorn[standard]'
|
|
```
|
|
|
|
**Add authentication later:**
|
|
```bash
|
|
# Use django-allauth-config skill
|
|
pip install django-allauth[socialaccount,mfa] django-cors-headers
|
|
```
|
|
|
|
## Integration with Other Skills
|
|
|
|
This skill integrates with:
|
|
|
|
- **mkcert-https-setup** - SSL certificate setup (referenced inline via platform-https guides)
|
|
- **django-allauth-config** - Add authentication after base setup
|
|
|
|
## Token Efficiency
|
|
|
|
**Core SKILL.md:** ~2,500 tokens (HTTPS-focused, no automation)
|
|
**Platform guides:** ~400-600 tokens (loaded only when needed)
|
|
**Troubleshooting:** ~300-500 tokens (loaded only on errors)
|
|
|
|
**Average context usage:** ~2,800 tokens
|
|
**Compared to v1.0 monolithic:** 65% reduction
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
# User says: "Set up Django project for HTTPS"
|
|
# Claude loads: django-project-setup skill
|
|
# Guides through: Python → venv → Django → mkcert → test HTTPS
|
|
```
|
|
|
|
## Final Project Structure
|
|
|
|
```
|
|
project-root/
|
|
├── backend/ # Django project
|
|
├── backend/views.py # Health + CSRF token endpoints
|
|
├── certs/ # mkcert SSL certificates
|
|
│ ├── localhost+2.pem
|
|
│ └── localhost+2-key.pem
|
|
├── venv/ # Virtual environment
|
|
├── .gitignore
|
|
├── db.sqlite3 # Database
|
|
├── manage.py
|
|
├── requirements.txt # Django, dotenv, DRF, cors-headers, uvicorn
|
|
├── run.sh # HTTPS server script (macOS/Linux)
|
|
├── run.bat # HTTPS server script (Windows)
|
|
└── .vscode/launch.json # Optional VS Code debug config
|
|
```
|
|
|
|
## Version History
|
|
|
|
- **v3.0.0** - HTTPS-only, mkcert integration, uvicorn server, CORS/CSRF defaults, minimal automation
|
|
- **v2.0.0** - Progressive disclosure with bundled content (deprecated)
|
|
- **v1.0.0** - Initial monolithic skill (deprecated)
|
|
|
|
## Security Notes
|
|
|
|
🔒 **Local development only** - mkcert certificates only work on your machine
|
|
🔐 **Never commit** - `certs/`, `*.pem`, `.env` must be in `.gitignore`
|
|
⚠️ **Production** - Use real SSL certificates (Let's Encrypt, etc.)
|