Configuration¶

This guide covers all configuration options for the Freeze Design webshop.

Environment Variables¶

BackendFrontend

File: backend/.env

# Django Settings
DEBUG=True
SECRET_KEY=your-secret-key-here
ALLOWED_HOSTS=localhost,127.0.0.1

# Database
DB_NAME=webshop_dev
DB_USER=webshop
DB_PASSWORD=your_password
DB_HOST=localhost
DB_PORT=5432

# Redis
REDIS_URL=redis://localhost:6379/1

# Celery
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=redis://localhost:6379/0

# CORS
CORS_ALLOWED_ORIGINS=http://localhost:3000
CSRF_TRUSTED_ORIGINS=http://localhost:3000

# Sentry (optional)
SENTRY_DSN=
SENTRY_ENVIRONMENT=development

# Email (Resend - magic link and transactional emails)
RESEND_API_KEY=
DEFAULT_FROM_EMAIL=noreply@notification.freezedesign.nl

# Frontend URL (for links in emails)
FRONTEND_URL=http://localhost:3000

# Mollie Payments
MOLLIE_API_KEY=test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Base URL only, no /api suffix (used to build Mollie webhook URLs)
BACKEND_URL=http://localhost:8000

# Media Storage (DigitalOcean Spaces, S3-compatible)
USE_SPACES=False
DO_SPACES_BUCKET_NAME=
DO_SPACES_ACCESS_KEY=
DO_SPACES_SECRET_KEY=
DO_SPACES_REGION=ams3

# AWS credentials (database backups, not media)
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_STORAGE_BUCKET_NAME=

See backend/.env.example for the full annotated list (Discord webhooks, backup configuration, etc.).

File: frontend/.env.local

# API
NEXT_PUBLIC_API_URL=http://localhost:8000/api

# Sentry
NEXT_PUBLIC_SENTRY_DSN=

# PostHog Analytics
NEXT_PUBLIC_POSTHOG_KEY=
NEXT_PUBLIC_POSTHOG_HOST=https://eu.i.posthog.com

PostHog

PostHog is instrumented on the frontend: instrumentation-client.ts initializes the SDK, PostHogProvider captures $pageview, and lib/posthog.ts exposes identifyUser and trackEvent helpers (plus e-commerce event wrappers). Event delivery simply depends on NEXT_PUBLIC_POSTHOG_KEY being set. Sentry remains the operational error tracker.

Django Settings¶

Key settings in backend/config/settings.py:

REST Framework¶

REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'config.pagination.StandardPagination',
    'PAGE_SIZE': 20,
    'DEFAULT_THROTTLE_RATES': {
        'anon': '5000/hour',
        'user': '10000/hour',
        'uploads': '20/hour',
        'checkout': '5/minute',
        'payment_retry': '3/minute',
    },
}

Throttling is disabled entirely when running tests or when E2E_TESTING=True.

Security Settings (Production)¶

SECURE_SSL_REDIRECT = True
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True
SECURE_HSTS_SECONDS = 31536000

Feature Flags¶

Control features via environment variables:

Variable	Default	Description
`DEBUG`	`False`	Enable debug mode. Defaults to off so a missing/unloaded `.env` fails closed — set `DEBUG=True` explicitly for local work (the `.env.example` template already does).
`E2E_TESTING`	`False`	Disable rate limiting for E2E tests
`CSP_REPORT_ONLY`	`False`	CSP in report-only mode (production/`DEBUG=False` only)

Logging¶

Configure logging levels in settings.py:

LOGGING = {
    'loggers': {
        'django': {'level': 'INFO'},
        'apps': {'level': 'INFO'},
    },
}

Log files are stored in backend/logs/: - django.log - General application logs - security.log - Security-related events

Config File Format¶

Local backend settings use dotenv syntax in backend/.env, copied from backend/.env.example. Frontend browser-visible settings use frontend/.env.local, based on frontend/.env.example. Docker Compose YAML supplies service-level overrides for local, staging, and production environments; application defaults remain in backend/config/settings.py and frontend/next.config.ts.

Never commit populated .env or .env.local files. Values prefixed with NEXT_PUBLIC_ are embedded in browser-delivered frontend code and therefore must never contain secrets.

Required vs Optional Settings¶

When DEBUG=False, Django's system checks require the following variables:

Variable	Required	Purpose
`SECRET_KEY`	Yes	Session, CSRF, and signing security.
`DB_PASSWORD`	Yes	PostgreSQL authentication.
`REDIS_URL`	Yes	Cache and session storage.
`MOLLIE_API_KEY`	Yes	Payment processing. Use a live key only for production.
`ALLOWED_HOSTS`	Yes	HTTP Host validation.
`CELERY_BROKER_URL`	Yes	Celery task broker.
`SENTRY_DSN`	Recommended	Error reporting; absence produces a deployment warning.
`RESEND_API_KEY`	Recommended	Transactional email; absence produces a deployment warning.

frontend/scripts/validate-env.mjs requires NEXT_PUBLIC_API_URL for staging builds and requires it to use HTTPS. PostHog configuration is optional; analytics stays disabled when NEXT_PUBLIC_POSTHOG_KEY is empty.

Defaults¶

Variable	Default	Source behavior
`DEBUG`	`False`	Fails closed: without it, an unloaded `.env` would silently drop secure cookies, HSTS and the strict CSP. Local `.env` sets `DEBUG=True`.
`DB_NAME` / `DB_USER`	`webshop_dev` / `webshop`	Local PostgreSQL defaults.
`DB_HOST` / `DB_PORT`	`localhost` / `5432`	Local database address.
`CONN_MAX_AGE`	`0` in debug, `600` otherwise	Database connection persistence.
`REDIS_URL`	`redis://localhost:6379/1`	Django cache and session store.
`FRONTEND_URL`	`http://localhost:3000`	Links generated by backend email/auth flows.
`BACKEND_URL`	`http://localhost:8000`	Mollie webhook base and default site URL.
`DO_SPACES_REGION`	`ams3`	Object-storage region when Spaces is enabled.
`BACKUP_S3_REGION` / `BACKUP_RETENTION_DAYS`	`eu-west-1` / `30`	Backup storage defaults.
`SENTRY_TRACES_SAMPLE_RATE`	`0.1`	Sentry transaction sampling.
`NEXT_PUBLIC_POSTHOG_HOST`	`/ingest` in deployed image builds	First-party PostHog proxy path.

Use the two .env.example files as the canonical annotated inventory; backend/config/settings.py contains additional operational tuning defaults for logging, health thresholds, company details, and security headers.

Per-environment Overrides¶

Development: use backend/.env and frontend/.env.local; docker-compose.dev.yml runs PostgreSQL, Redis, and RabbitMQ.
Test/CI: workflows set explicit test variables and services. E2E_TESTING=True is allowed only in non-production test environments and disables selected security controls.
Staging: GitHub Actions passes build arguments and server-side secrets to docker-compose.staging.yml; the frontend staging validator rejects a non-HTTPS API URL.
Production: docker-compose.prod.yml consumes server-managed environment values. Run python manage.py check --deploy and never enable E2E_TESTING.