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