Skip to content

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 an 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. Services typically run via Docker, security is relaxed, and email is routed to the console.

Test
Used for automated testing. Configuration mirrors production but uses isolated infrastructure and credentials.

Staging
Used for pre‑production validation. Integrations and security closely resemble 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 by: - environment variables - the selected settings module - infrastructure configuration

Settings structure

Configuration is layered to keep responsibilities clear.

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

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

Runtime injection
Sensitive values (secrets, credentials, endpoints) are injected via environment variables and are not committed to source control.

Configuration sources

Configuration values originate from the following sources, in order of precedence.

Environment variables
Primary configuration mechanism for secrets, credentials, feature flags, and infrastructure details.

.env file (local development only)
For local development, a .env file is loaded to provide required environment variables. This file must never be committed.

Settings modules
Django settings files define defaults, structure, and controlled fallbacks.

Important settings and their impact

Application identity

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

APP_NAME
Human‑readable application name used in emails and notifications.

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

Debug and security

DEBUG
Controls debug output and relaxed security behavior. 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
Explicit list of allowed hostnames. In production this is locked down to known domains only.

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

Database configuration

ReFlux uses PostgreSQL as its primary datastore.

Database configuration is fully environment‑driven via variables such as: - database name - user credentials - host and port

This allows environment isolation without code changes.

REST API configuration

The backend exposes a REST API using Django REST Framework.

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

These defaults ensure consistent API behavior across web and mobile clients.

Authentication and authorization

AUTH_USER_MODEL
A custom user model owned by the accounts domain.

Authentication backends
Standard Django authentication is combined with Axes to protect against 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.

Configuration defines: - Redis broker location - serialization formats - task imports - timezone alignment - scheduled execution via django‑celery‑beat

This ensures background processing remains consistent 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 via environment variables.

Storage and uploads

Static files
Served using WhiteNoise with compressed and versioned 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 via settings for: - retention duration - delivery retries and backoff strategy - rate limiting - push notification providers

This allows operational tuning without code changes.

Email delivery

Email behavior is environment‑specific.

Development
Emails are printed to the console.

Production
SMTP delivery is enabled (for example Office365), with credentials injected via environment variables.

Design intent

The settings model is designed to:

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

Domain logic does not depend directly on environment‑specific settings.