thrillwiki_django_no_react/shared/docs/DEVELOPMENT_SETUP.md

ThrillWiki Development Setup

This guide explains how to run the ThrillWiki project without requiring the scripts/dev_server.sh shell script.

Quick Start (Recommended)

The easiest way to get started is using the new Django management commands:

# One-time setup and run the server
python manage.py rundev

# Or just set up the environment (without starting the server)
python manage.py setup_dev

# Then run the server separately
python manage.py runserver

Manual Setup

If you prefer to set things up manually or customize your environment:

1. Environment Variables

Copy the provided .env file or create your own:

cp .env.example .env
# Edit .env with your specific configuration

The .env file should contain all necessary environment variables. Key variables include:

# Django settings
DJANGO_SETTINGS_MODULE=config.django.local
DEBUG=True
SECRET_KEY=your-secret-key-here

# Database (PostgreSQL with PostGIS required)
DATABASE_URL=postgis://username:password@localhost:5432/database_name

# GeoDjango library paths (adjust for your system)
GDAL_LIBRARY_PATH=/opt/homebrew/lib/libgdal.dylib  # macOS with Homebrew
GEOS_LIBRARY_PATH=/opt/homebrew/lib/libgeos_c.dylib

# For Linux:
# GDAL_LIBRARY_PATH=/usr/lib/libgdal.so
# GEOS_LIBRARY_PATH=/usr/lib/libgeos_c.so

2. Virtual Environment (Recommended)

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# or
.venv\\Scripts\\activate  # Windows

# Install dependencies
pip install -r requirements.txt

3. Database Setup

Make sure you have PostgreSQL with PostGIS extension installed and running:

# Create database and user (adjust as needed)
createdb thrillwiki_test_db
psql -d thrillwiki_test_db -c "CREATE EXTENSION postgis;"

# Run migrations
python manage.py migrate

4. Static Files and Assets

# Create necessary directories
mkdir -p logs profiles media staticfiles static/css

# Collect static files
python manage.py collectstatic --noinput

# Build Tailwind CSS (if you have npm installed)
python manage.py tailwind build

5. Create Superuser

python manage.py createsuperuser
# or use the predefined admin/admin user:
python manage.py shell -c "
from django.contrib.auth import get_user_model
User = get_user_model()
if not User.objects.filter(username='admin').exists():
    User.objects.create_superuser('admin', 'admin@example.com', 'admin')
"

6. Run the Server

python manage.py runserver
# or if you have django-extensions installed:
python manage.py runserver_plus

Available Management Commands

The project now includes several helpful management commands:

rundev

Automatically sets up the development environment and starts the server:

# Full setup and start server
python manage.py rundev

# Skip setup, just start server
python manage.py rundev --skip-setup

# Use different port
python manage.py rundev --port 8080

# Use runserver_plus if available
python manage.py rundev --use-runserver-plus

setup_dev

Sets up the development environment without starting the server:

# Full setup
python manage.py setup_dev

# Skip specific steps
python manage.py setup_dev --skip-migrations
python manage.py setup_dev --skip-static
python manage.py setup_dev --skip-tailwind
python manage.py setup_dev --skip-superuser

Environment Configuration

The project supports multiple environments through different settings modules:

• Local Development: config.django.local (default)
• Production: config.django.production
• Testing: config.django.test

Environment Auto-Detection

The manage.py script automatically detects the appropriate environment based on:

1. Existing DJANGO_SETTINGS_MODULE environment variable
2. Command line arguments (test command)
3. Production environment indicators (Heroku, AWS, Kubernetes, etc.)
4. DEBUG environment variable setting

Manual Environment Override

You can override environment detection by setting the DJANGO_SETTINGS_MODULE environment variable:

export DJANGO_SETTINGS_MODULE=config.django.production
python manage.py runserver

Troubleshooting

Common Issues

1. ImportError: Couldn't import Django

   • Make sure Django is installed: pip install django
   • Check that your virtual environment is activated
   • Try: python manage.py setup_dev

2. Database connection errors

   • Verify PostgreSQL is running
   • Check your DATABASE_URL in .env
   • Ensure PostGIS extension is installed: CREATE EXTENSION postgis;

3. GeoDjango library path errors

   • Update GDAL_LIBRARY_PATH and GEOS_LIBRARY_PATH in .env
   • For macOS with Homebrew: /opt/homebrew/lib/libgdal.dylib
   • For Linux: /usr/lib/libgdal.so or /usr/lib/x86_64-linux-gnu/libgdal.so

4. Static files not loading

   • Run: python manage.py collectstatic
   • For development, ensure DEBUG=True in your .env

5. Tailwind CSS not building

   • Install Node.js and npm
   • Run: python manage.py tailwind build

Getting Help

• Check the logs in the logs/ directory
• Use Django's built-in error pages when DEBUG=True
• Run system checks: python manage.py check

Comparison with dev_server.sh

The new setup provides the same functionality as the original scripts/dev_server.sh but with more flexibility:

Feature	dev_server.sh	New Setup
Environment variables	Hard-coded in script	Configurable via .env
Setup steps	All-or-nothing	Selective with flags
Cross-platform	bash-only	Python (cross-platform)
Customization	Edit script	Command arguments
Integration	External script	Django management commands

You can still use the original script if preferred, but the new approach provides better integration with Django's ecosystem and more flexibility for different development workflows.