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)

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

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

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

# Inside WSL2, follow Linux instructions above

Step-by-Step Setup

1. Clone the Repository

git clone <repository-url>
cd thrillwiki

2. Database Setup

Create PostgreSQL Database

# 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

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

3. Install Python Dependencies

cd backend

# Install dependencies with UV
uv sync --frozen

# Or allow updates within version constraints
uv sync

4. Configure Environment Variables

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

Edit .env with your settings:

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

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

5. Run Database Migrations

cd backend
uv run manage.py migrate

6. Create Superuser

uv run manage.py createsuperuser

7. Collect Static Files (Optional for Development)

uv run manage.py collectstatic --noinput

8. Start Development Server

uv run manage.py runserver

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

Verification

Check Django Configuration

uv run manage.py check

Validate Settings

uv run manage.py validate_settings

Run Tests

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:

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

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

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

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

# 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

# Install with profiling group
uv sync --group profiling

# Debug toolbar is enabled by default in local.py

Configure Email for Development

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

Load Sample Data

# 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

cd backend
uv run manage.py runserver

Running with Celery (for background tasks)

# 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

# Format code
uv run black .
uv run isort .

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

# Type checking
uv run pyright

Making Changes

# 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
4. Review Architecture: Architecture Decisions

Getting Help

• Check Common Issues above
• Review Environment Variables
• See Backend README for development details