Add secret management guide, client-side performance monitoring, and search accessibility enhancements

- Introduced a comprehensive Secret Management Guide detailing best practices, secret classification, development setup, production management, rotation procedures, and emergency protocols. - Implemented a client-side performance monitoring script to track various metrics including page load performance, paint metrics, layout shifts, and memory usage. - Enhanced search accessibility with keyboard navigation support for search results, ensuring compliance with WCAG standards and improving user experience.
2025-12-24 17:11:09 -05:00 · 2025-12-23 16:41:42 -05:00
parent ae31e889d7
commit edcd8f2076
155 changed files with 22046 additions and 4645 deletions
--- a/docs/SETUP_GUIDE.md
+++ b/docs/SETUP_GUIDE.md
@@ -0,0 +1,368 @@
+# 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