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:

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

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

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

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

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

```bash
# 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

```bash
# 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

```bash
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

```bash
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:

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

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

```bash
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.