Configuration¶
This guide covers all configuration options for the Freeze Design webshop.
Environment Variables¶
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
# Database backups (S3-compatible; read by apps/core/services/backup_service.py)
BACKUP_S3_BUCKET=
BACKUP_S3_ACCESS_KEY=
BACKUP_S3_SECRET_KEY=
BACKUP_S3_REGION=eu-west-1
# Leave unset for AWS S3; set for DigitalOcean Spaces
BACKUP_S3_ENDPOINT_URL=
BACKUP_RETENTION_DAYS=30
See backend/.env.example for the annotated development list (Discord webhooks, PostHog and Sentry API tokens, GOOGLE_PLACES_API_KEY for the review block, RESEND_SEGMENT_ID for the newsletter) and backend/.env.staging.example / backend/.env.production.example for the server variants (backup settings, company details for invoices). The Informer bookkeeping keys (INFORMER_API_KEY, INFORMER_SECRET_KEY, INFORMER_ALLOW_WRITES) exist on production only and are set by Ivar; without INFORMER_ALLOW_WRITES=True the link only reads (proefstand). All three files also list the notification and Freeze AI variables, which do nothing while empty: NTFY_URL, NTFY_TOKEN, NTFY_TITLE_PREFIX, NTFY_FALLBACK_URL and NOTIFY_FALLBACK_EMAIL (ntfy next to Discord, see ntfy notifications), HEALTHCHECK_PING_URL and NTFY_HEARTBEAT_PING_URL (healthchecks.io pings), and AGENT_API_ALLOWED_IPS, FREEZE_AI_AGENT_URL, FREEZE_AI_AGENT_TOKEN and FREEZE_AI_ENV (staging or prod) for the Freeze AI agent (see agent API).
File: frontend/.env.local
# API
NEXT_PUBLIC_API_URL=http://localhost:8000/api
# Sentry (DSN is public; the auth token is only used for source-map uploads at build time)
NEXT_PUBLIC_SENTRY_DSN=
SENTRY_AUTH_TOKEN=
# PostHog Analytics
NEXT_PUBLIC_POSTHOG_KEY=
NEXT_PUBLIC_POSTHOG_HOST=https://eu.i.posthog.com
./manage.sh setup writes a minimal .env.local with only NEXT_PUBLIC_API_URL; copy frontend/.env.example if you want the optional keys.
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': API_THROTTLE_RATES, # see below
}
API_THROTTLE_RATES = {
'anon': '5000/hour',
'user': '10000/hour',
'uploads': '20/hour',
'checkout': '5/minute',
'payment_retry': '3/minute',
'payment_webhook': '120/min',
'resend_verification': '5/hour',
'newsletter': '10/hour',
'design_create_hour': '30/hour', # anonymous POST /api/designs/, per IP
'design_create_day': '100/day',
}
Throttling is disabled entirely when running tests or when E2E_TESTING=True (and E2E_TESTING is ignored while pytest runs). E2E_TESTING also disables django-axes and makes email verification optional, which is why it must never be set outside DEBUG environments.
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:
All logs go to stdout; there are no log files. In Docker, read them with docker compose -f <compose file> logs <service>. The compose files for staging and production cap the log size per container (the logging block).
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, the system checks in backend/config/checks.py (python manage.py check --deploy) require the following variables:
| Variable | Required | Purpose |
|---|---|---|
SECRET_KEY |
Yes | Session, CSRF, and signing security (a django-insecure value counts as missing). |
DB_PASSWORD |
Yes | PostgreSQL authentication. |
REDIS_URL |
Yes | Cache and session storage. |
MOLLIE_API_KEY |
Yes | Payment processing. A test_ key outside DEBUG produces a warning unless ALLOW_TEST_MOLLIE_KEY=True. |
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. |
The same checks fail when E2E_TESTING=True is set outside DEBUG.
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.
Customer-facing features are switched in the admin, not through environment variables: SiteSettings holds stock_management_enabled, team_order_enabled, all_payment_methods_enabled, cart_reminder_enabled, review_request_enabled, newsletter_enabled, whatsapp_buttons_enabled, catalog_color_swatches_enabled, shop_order_email_enabled and informer_mode (off | preview | live). New switches default to off; read the live state from GET /api/settings/.
Per-environment Overrides¶
- Development: use
backend/.envandfrontend/.env.local;docker-compose.dev.ymlruns PostgreSQL, Redis, and RabbitMQ. - Test/CI: workflows set explicit test variables and services.
E2E_TESTING=Trueis 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.ymlconsumes server-managed environment values. Runpython manage.py check --deployand never enableE2E_TESTING.
Values stored in GitHub Actions secrets or on the servers are not in the repository; review them in those systems before a deployment.