mirror of
https://github.com/pacnpal/thrillwiki_django_no_react.git
synced 2025-12-24 15:31:09 -05:00
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.
This commit is contained in:
pacnpal
259
docs/configuration/README.md
Normal file
259
docs/configuration/README.md
Normal file
@@ -0,0 +1,259 @@
|
||||
# ThrillWiki Configuration System
|
||||
|
||||
This document provides an overview of the ThrillWiki configuration system, including how settings are organized, how to configure different environments, and best practices for managing configuration.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
ThrillWiki uses a modular configuration architecture that separates concerns and makes settings easy to manage across different environments.
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
backend/config/
|
||||
├── django/ # Environment-specific settings
|
||||
│ ├── base.py # Core Django settings (imports from settings/)
|
||||
│ ├── local.py # Local development settings
|
||||
│ ├── production.py # Production settings
|
||||
│ └── test.py # Test settings
|
||||
├── settings/ # Modular settings modules
|
||||
│ ├── __init__.py # Package documentation
|
||||
│ ├── cache.py # Redis caching configuration
|
||||
│ ├── database.py # Database and GeoDjango settings
|
||||
│ ├── email.py # Email backend configuration
|
||||
│ ├── logging.py # Logging formatters, handlers, loggers
|
||||
│ ├── rest_framework.py # DRF, JWT, CORS, API docs
|
||||
│ ├── secrets.py # Secret management utilities
|
||||
│ ├── security.py # Security headers and authentication
|
||||
│ ├── storage.py # Static/media files and WhiteNoise
|
||||
│ ├── third_party.py # Allauth, Celery, Cloudflare, etc.
|
||||
│ └── validation.py # Environment variable validation
|
||||
└── celery.py # Celery task queue configuration
|
||||
```
|
||||
|
||||
### How Settings Are Loaded
|
||||
|
||||
1. **base.py** defines core Django settings and imports all modular settings
|
||||
2. Environment-specific files (**local.py**, **production.py**, **test.py**) extend base.py
|
||||
3. The active settings module is determined by `DJANGO_SETTINGS_MODULE`
|
||||
4. Modular settings use **python-decouple** to read environment variables
|
||||
|
||||
### Environment Selection
|
||||
|
||||
The settings module is selected in this order:
|
||||
|
||||
1. `DJANGO_SETTINGS_MODULE` environment variable (explicit override)
|
||||
2. Test command detection (`manage.py test` → `config.django.test`)
|
||||
3. Production indicators (cloud provider environment variables)
|
||||
4. `DEBUG=False` → `config.django.production`
|
||||
5. Default → `config.django.local`
|
||||
|
||||
## Configuration Methods
|
||||
|
||||
### Using Environment Variables
|
||||
|
||||
Environment variables are the primary configuration method. Create a `.env` file from the template:
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# Edit .env with your values
|
||||
```
|
||||
|
||||
### python-decouple
|
||||
|
||||
All settings modules use python-decouple for consistent environment variable handling:
|
||||
|
||||
```python
|
||||
from decouple import config
|
||||
|
||||
# String with default
|
||||
DEBUG = config("DEBUG", default=True, cast=bool)
|
||||
|
||||
# Integer with validation
|
||||
PORT = config("PORT", default=8000, cast=int)
|
||||
|
||||
# List from comma-separated string
|
||||
ALLOWED_HOSTS = config(
|
||||
"ALLOWED_HOSTS",
|
||||
default="localhost",
|
||||
cast=lambda v: [s.strip() for s in v.split(",")]
|
||||
)
|
||||
```
|
||||
|
||||
## Environment-Specific Configuration
|
||||
|
||||
### Local Development (`config.django.local`)
|
||||
|
||||
- Debug mode enabled
|
||||
- Local memory cache (no Redis required)
|
||||
- Console email backend
|
||||
- Development middleware (nplusone, debug toolbar)
|
||||
- Relaxed security settings
|
||||
|
||||
### Production (`config.django.production`)
|
||||
|
||||
- Debug mode disabled
|
||||
- Redis caching required
|
||||
- Strict security settings (HSTS, secure cookies)
|
||||
- JSON logging for log aggregation
|
||||
- Sentry integration (optional)
|
||||
|
||||
### Test (`config.django.test`)
|
||||
|
||||
- In-memory SpatiaLite database
|
||||
- In-memory cache
|
||||
- Fast password hashing
|
||||
- Logging disabled
|
||||
- Celery tasks run synchronously
|
||||
|
||||
## Modular Settings Reference
|
||||
|
||||
### database.py
|
||||
|
||||
- `DATABASES` - Database connection configuration
|
||||
- `GDAL_LIBRARY_PATH`, `GEOS_LIBRARY_PATH` - GeoDjango libraries
|
||||
- `CONN_MAX_AGE` - Connection pooling
|
||||
- `DATABASE_OPTIONS` - PostgreSQL-specific settings
|
||||
|
||||
### cache.py
|
||||
|
||||
- `CACHES` - Redis cache backends (default, sessions, api)
|
||||
- `SESSION_*` - Session storage settings
|
||||
- `CACHE_MIDDLEWARE_*` - Cache middleware settings
|
||||
|
||||
### security.py
|
||||
|
||||
- `SECURE_*` - Security header settings
|
||||
- `SESSION_COOKIE_*`, `CSRF_COOKIE_*` - Cookie security
|
||||
- `AUTH_PASSWORD_VALIDATORS` - Password validation rules
|
||||
- `PERMISSIONS_POLICY` - Browser feature permissions
|
||||
|
||||
### email.py
|
||||
|
||||
- `EMAIL_BACKEND` - Email sending backend
|
||||
- `FORWARD_EMAIL_*` - ForwardEmail configuration
|
||||
- SMTP settings for custom email servers
|
||||
|
||||
### rest_framework.py
|
||||
|
||||
- `REST_FRAMEWORK` - DRF configuration
|
||||
- `CORS_*` - Cross-origin settings
|
||||
- `SIMPLE_JWT` - JWT token settings
|
||||
- `REST_AUTH` - dj-rest-auth settings
|
||||
- `SPECTACULAR_SETTINGS` - OpenAPI documentation
|
||||
|
||||
### third_party.py
|
||||
|
||||
- `ACCOUNT_*`, `SOCIALACCOUNT_*` - Allauth settings
|
||||
- `CLOUDFLARE_IMAGES` - Image CDN configuration
|
||||
- `ROADTRIP_*` - Road trip service settings
|
||||
- `HEALTH_CHECK` - Health check thresholds
|
||||
|
||||
### storage.py
|
||||
|
||||
- `STATIC_*`, `MEDIA_*` - File serving configuration
|
||||
- `STORAGES` - Django 4.2+ storage backends
|
||||
- `WHITENOISE_*` - Static file optimization
|
||||
- `FILE_UPLOAD_*` - Upload security limits
|
||||
|
||||
### logging.py
|
||||
|
||||
- `LOGGING` - Complete logging configuration
|
||||
- Formatters: verbose, json, simple
|
||||
- Handlers: console, file, error_file, performance
|
||||
- Loggers for Django, application, and third-party
|
||||
|
||||
## Secret Management
|
||||
|
||||
### Validation
|
||||
|
||||
Use the management command to validate configuration:
|
||||
|
||||
```bash
|
||||
# Full validation
|
||||
python manage.py validate_settings
|
||||
|
||||
# Strict mode (warnings become errors)
|
||||
python manage.py validate_settings --strict
|
||||
|
||||
# JSON output
|
||||
python manage.py validate_settings --json
|
||||
|
||||
# Secrets only
|
||||
python manage.py validate_settings --secrets-only
|
||||
```
|
||||
|
||||
### Required Secrets
|
||||
|
||||
These secrets must be set in all environments:
|
||||
|
||||
| Secret | Description |
|
||||
|--------|-------------|
|
||||
| `SECRET_KEY` | Django cryptographic signing key (50+ chars) |
|
||||
| `DATABASE_URL` | Database connection URL |
|
||||
|
||||
### Secret Rotation
|
||||
|
||||
For production environments:
|
||||
|
||||
1. Enable rotation checking: `SECRET_ROTATION_ENABLED=True`
|
||||
2. Track versions: `SECRET_KEY_VERSION=1`
|
||||
3. Monitor expiry warnings in logs
|
||||
4. Rotate secrets before expiry
|
||||
|
||||
See [Secret Management Guide](./secret-management.md) for detailed procedures.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Settings module not found:**
|
||||
```
|
||||
ModuleNotFoundError: No module named 'config.django.local'
|
||||
```
|
||||
Ensure you're running commands from the `backend/` directory.
|
||||
|
||||
**Required environment variable missing:**
|
||||
```
|
||||
decouple.UndefinedValueError: SECRET_KEY not found
|
||||
```
|
||||
Create a `.env` file or set the environment variable.
|
||||
|
||||
**Database connection failed:**
|
||||
```
|
||||
django.db.utils.OperationalError: could not connect to server
|
||||
```
|
||||
Check `DATABASE_URL` format and database server status.
|
||||
|
||||
### Validation Errors
|
||||
|
||||
Run validation to identify configuration issues:
|
||||
|
||||
```bash
|
||||
python manage.py validate_settings
|
||||
```
|
||||
|
||||
### Debug Configuration
|
||||
|
||||
To debug configuration loading:
|
||||
|
||||
```python
|
||||
# In Django shell
|
||||
from django.conf import settings
|
||||
print(settings.DEBUG)
|
||||
print(settings.DATABASES)
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Never commit secrets** - Use `.env` files or secret management services
|
||||
2. **Use environment variables** - Don't hardcode configuration values
|
||||
3. **Validate on startup** - Catch configuration errors early
|
||||
4. **Separate environments** - Use different settings for dev/staging/production
|
||||
5. **Document custom settings** - Add comments explaining non-obvious configuration
|
||||
6. **Use appropriate defaults** - Secure defaults for production, convenient for development
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Environment Variables Reference](./environment-variables.md)
|
||||
- [Secret Management Guide](./secret-management.md)
|
||||
- [Deployment Guide](./deployment.md)
|
||||
Reference in New Issue
Block a user