thrillwiki_django_no_react/docs/SETUP_GUIDE.md

# ThrillWiki Setup Guide

This guide provides comprehensive instructions for setting up the ThrillWiki development environment.

## Prerequisites

### Required Software

| Software | Minimum Version | Notes |
|----------|----------------|-------|
| Python | 3.13+ | Required for Django 5.2 |
| PostgreSQL | 14+ | With PostGIS extension |
| Redis | 6+ | For caching and sessions |
| UV | Latest | Python package manager |

### Platform-Specific Prerequisites

#### macOS (with Homebrew)

```bash
# Install Homebrew if not present
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install python@3.13 postgresql@15 postgis redis gdal geos proj

# Start services
brew services start postgresql@15
brew services start redis

# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh
```

#### Linux (Ubuntu/Debian)

```bash
# Update package list
sudo apt update

# Install Python 3.13
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt install python3.13 python3.13-venv python3.13-dev

# Install PostgreSQL with PostGIS
sudo apt install postgresql-15 postgresql-15-postgis-3 postgresql-contrib

# Install Redis
sudo apt install redis-server

# Install GDAL and GEOS for GeoDjango
sudo apt install libgdal-dev libgeos-dev binutils libproj-dev

# Start services
sudo systemctl start postgresql
sudo systemctl start redis

# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh
```

#### Windows (with WSL2)

```bash
# Use WSL2 with Ubuntu
wsl --install -d Ubuntu

# Inside WSL2, follow Linux instructions above
```

## Step-by-Step Setup

### 1. Clone the Repository

```bash
git clone <repository-url>
cd thrillwiki
```

### 2. Database Setup

#### Create PostgreSQL Database

```bash
# Access PostgreSQL
sudo -u postgres psql

# Create database and user
CREATE USER thrillwiki WITH PASSWORD 'your-password';
CREATE DATABASE thrillwiki OWNER thrillwiki;

# Enable PostGIS extension
\c thrillwiki
CREATE EXTENSION postgis;
CREATE EXTENSION postgis_topology;

# Grant privileges
GRANT ALL PRIVILEGES ON DATABASE thrillwiki TO thrillwiki;
\q
```

#### Verify PostGIS Installation

```bash
sudo -u postgres psql -d thrillwiki -c "SELECT PostGIS_version();"
```

### 3. Install Python Dependencies

```bash
cd backend

# Install dependencies with UV
uv sync --frozen

# Or allow updates within version constraints
uv sync
```

### 4. Configure Environment Variables

```bash
# Copy example environment file
cp .env.example .env
```

Edit `.env` with your settings:

```bash
# Required settings
SECRET_KEY=generate-a-secure-key-here
DEBUG=True
DJANGO_SETTINGS_MODULE=config.django.local
ALLOWED_HOSTS=localhost,127.0.0.1

# Database
DATABASE_URL=postgis://thrillwiki:your-password@localhost:5432/thrillwiki

# Redis
REDIS_URL=redis://localhost:6379/1

# GeoDjango (macOS with Homebrew)
GDAL_LIBRARY_PATH=/opt/homebrew/lib/libgdal.dylib
GEOS_LIBRARY_PATH=/opt/homebrew/lib/libgeos_c.dylib
```

Generate a secure secret key:

```bash
python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"
```

### 5. Run Database Migrations

```bash
cd backend
uv run manage.py migrate
```

### 6. Create Superuser

```bash
uv run manage.py createsuperuser
```

### 7. Collect Static Files (Optional for Development)

```bash
uv run manage.py collectstatic --noinput
```

### 8. Start Development Server

```bash
uv run manage.py runserver
```

The application will be available at `http://localhost:8000`.

## Verification

### Check Django Configuration

```bash
uv run manage.py check
```

### Validate Settings

```bash
uv run manage.py validate_settings
```

### Run Tests

```bash
uv run manage.py test
```

### Access Admin Panel

1. Navigate to `http://localhost:8000/admin/`
2. Login with superuser credentials

## Common Setup Issues

### Issue: PostGIS Not Found

**Error**: `Could not find the GDAL library`

**Solution**:
```bash
# macOS
export GDAL_LIBRARY_PATH=/opt/homebrew/lib/libgdal.dylib
export GEOS_LIBRARY_PATH=/opt/homebrew/lib/libgeos_c.dylib

# Add to .env file for persistence
```

### Issue: Database Connection Error

**Error**: `could not connect to server`

**Solution**:
```bash
# Check PostgreSQL is running
sudo systemctl status postgresql  # Linux
brew services list               # macOS

# Check connection string
psql $DATABASE_URL
```

### Issue: Redis Connection Error

**Error**: `Error connecting to Redis`

**Solution**:
```bash
# Check Redis is running
redis-cli ping
# Should return: PONG

# Start Redis if not running
sudo systemctl start redis  # Linux
brew services start redis   # macOS
```

### Issue: Python Version Mismatch

**Error**: `Python 3.13+ required`

**Solution**:
```bash
# Check Python version
python --version

# Use specific Python version with UV
UV_PYTHON=python3.13 uv sync
```

### Issue: Migration Errors

**Error**: `django.db.utils.ProgrammingError`

**Solution**:
```bash
# Reset migrations (development only!)
uv run manage.py migrate --fake-initial

# Or recreate database
sudo -u postgres dropdb thrillwiki
sudo -u postgres createdb thrillwiki -O thrillwiki
sudo -u postgres psql -d thrillwiki -c "CREATE EXTENSION postgis;"
uv run manage.py migrate
```

## Optional Configuration

### Enable Debug Toolbar

```bash
# Install with profiling group
uv sync --group profiling

# Debug toolbar is enabled by default in local.py
```

### Configure Email for Development

```python
# Uses console backend by default
# Emails are printed to console in development
EMAIL_BACKEND=django.core.mail.backends.console.EmailBackend
```

### Load Sample Data

```bash
# If sample data fixtures exist
uv run manage.py loaddata sample_parks.json
uv run manage.py loaddata sample_rides.json
```

## Development Workflow

### Running the Server

```bash
cd backend
uv run manage.py runserver
```

### Running with Celery (for background tasks)

```bash
# Terminal 1: Django server
uv run manage.py runserver

# Terminal 2: Celery worker
uv run celery -A config.celery worker -l info

# Terminal 3: Celery beat (for scheduled tasks)
uv run celery -A config.celery beat -l info
```

### Code Quality Commands

```bash
# Format code
uv run black .
uv run isort .

# Lint code
uv run ruff check .
uv run flake8 .

# Type checking
uv run pyright
```

### Making Changes

```bash
# Create migrations after model changes
uv run manage.py makemigrations

# Apply migrations
uv run manage.py migrate

# Run tests
uv run manage.py test
```

## Next Steps

After completing setup:

1. **Explore the Admin Panel**: `/admin/`
2. **View API Documentation**: `/api/docs/`
3. **Read HTMX Patterns**: [htmx-patterns.md](./htmx-patterns.md)
4. **Review Architecture**: [Architecture Decisions](./architecture/)

## Getting Help

- Check [Common Issues](#common-setup-issues) above
- Review [Environment Variables](./configuration/environment-variables.md)
- See [Backend README](../backend/README.md) for development details