Settings & Environments¶

This page describes how configuration is structured in the ReFlux backend, how different environments are managed, and which settings are especially important for correct and secure operation.

The backend follows a environment‑driven configuration model, where most behavior is controlled via environment variables and minimal environment‑specific overrides.

Environments¶

ReFlux supports the following runtime environments:

Local
Used for local development on a developer machine. All services typically run via Docker, relaxed security settings apply, and emails are sent to the console.

Test
Used for automated testing and validation. Configuration mirrors production closely, but with test credentials and isolated databases.

Staging
Used for pre‑production validation. Integrations, security, and infrastructure closely match production, but data is non‑critical.

Production
Live environment for real users. Security hardening, strict host validation, and real external integrations are enabled.

Each environment is distinguished through: - environment variables - selected settings module - infrastructure configuration

Settings structure¶

Configuration is layered to keep concerns separated.

Base settings
The base settings module defines all common configuration shared across environments. This includes installed apps, middleware, authentication, REST framework defaults, logging, and integrations.

Environment-specific settings
Development and production settings import from the base module and override only what is environment‑dependent (for example DEBUG flags, allowed hosts, and security headers).

Runtime injection
Sensitive values and deployment‑specific configuration are injected at runtime via environment variables rather than committed to source control.

Configuration sources¶

Configuration values originate from multiple sources, in order of precedence.

Environment variables
The primary configuration mechanism. Values such as secrets, database credentials, hostnames, and feature flags are read from environment variables.

.env file (local development only)
In local environments, a .env file is loaded to provide required environment variables without manual export. This file must never be committed.

Settings modules
Django settings files define defaults, structure, and sane fallbacks when possible.

Important settings and their impact¶

Application identity¶

APP_VERSION
Defines the backend application version exposed to clients and documentation.

APP_NAME
Used for human‑readable labeling in emails and notifications.

TIME_ZONE
All time handling is normalized to Europe/Amsterdam. This is important for planning, timesheets, and reporting.

Debug and security¶

DEBUG
Controls debug output and relaxed security. Must be disabled in production.

SECRET_KEY
Cryptographic secret used by Django. Must be unique and kept secure in all non‑development environments.

ALLOWED_HOSTS
Defines which hostnames are permitted to serve requests. In production this is explicitly locked down.

CSRF / session security
Production settings enable secure cookies and trusted origins to prevent request forgery and session leakage.

Database configuration¶

The backend uses PostgreSQL as its primary datastore.

Key settings include: - database name - user credentials - host and port

All database configuration is injected via environment variables, making it easy to swap databases per environment without code changes.

REST API configuration¶

The backend exposes a REST API using Django REST Framework.

Key behaviors include: - JWT‑based authentication - authenticated access by default - request throttling to protect against abuse - pagination defaults for list endpoints - OpenAPI schema generation via drf‑spectacular

These defaults ensure consistent API behavior across all clients.

Authentication and authorization¶

AUTH_USER_MODEL
A custom user model is used, owned by the accounts domain.

Authentication backends
Standard Django authentication is combined with Axes protection to mitigate brute‑force login attempts.

JWT configuration
Access tokens are short‑lived, refresh tokens rotate, and blacklisting is enabled to improve security.

Background processing¶

Asynchronous work is handled using Celery.

Key settings define: - Redis broker location - serialization format - task imports - timezone alignment - scheduled job handling via django‑celery‑beat

This ensures background processing behaves consistently with request‑time logic.

Real‑time communication¶

Django Channels is used to support real‑time features such as chat.

Channel layers are backed by Redis, and configuration is shared across environments through environment variables.

Storage and uploads¶

Static files
Served using WhiteNoise with compressed manifests.

Media files
Stored locally in development and optionally backed by S3‑compatible storage in production.

Upload limits
Maximum upload size and allowed MIME types are enforced centrally to protect system resources.

Notifications¶

Notification behavior is controlled through configuration for: - retention duration - delivery retries and backoff strategy - rate limiting - push providers (e.g. Expo)

These settings allow fine‑tuning reliability without code changes.

Email delivery¶

Email configuration is environment‑dependent.

In development: - emails are printed to the console

In production: - SMTP configuration (for example Office365) is enabled - credentials are injected via environment variables

Design intent¶

The settings model is intentionally designed to:

keep secrets out of source control
minimize environment‑specific code
allow safe production defaults
support containerized deployments
make configuration explicit and auditable

No domain logic depends directly on environment specifics.