WEBDIENSTE/lasuite-messages
1
0
Fork 0
mirror of https://github.com/suitenumerique/messages.git synced 2026-09-05 09:27:45 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
ae1d9db95ab2e63eef58bb42c837ee605daa48a3
lasuite-messages/docs/env.md
T
jbpenrath f2c407f6a0 🌐(frontend) manage translation keys through i18next-cli 
Rework totally the way to manage frontend translation keys. Currently we were
managing manually all those keys but now we want to use crowdin to manage our
languages so first we need to be able to extract frontend translation keys in
dedicated files.

Furthermore, we allow to setup frontend application languages and default
language through environment variables
(NEXT_PUBLIC_DEFAULT_LANGUAGE and NEXT_PUBLIC_LANGUAGES)
2025-10-06 10:06:14 +02:00

15 KiB
Raw Blame History

Environment Variables

This document provides a comprehensive overview of all environment variables used in the Messages application. These variables are organized by service and functionality.

Development Environment

Environment Files Structure

The application uses a new environment file structure with .defaults and .local files:

  • *.defaults - Committed default configurations
  • *.local - Gitignored local overrides (created by make bootstrap)

Available Environment Files

  • backend.defaults - Main Django application settings
  • common.defaults - Shared settings across services
  • frontend.defaults - Frontend configuration
  • postgresql.defaults - PostgreSQL database configuration
  • keycloak.defaults - Keycloak configuration
  • mta-in.defaults - Inbound mail server settings
  • mta-out.defaults - Outbound mail server settings
  • crowdin.defaults - Translation service configuration

Core Application Configuration

Django Settings

Variable Default Description Required
DJANGO_CONFIGURATION Development Django configuration class to use (Development, Production, Test, etc.) Required
DJANGO_SECRET_KEY None Secret key for cryptographic signing Required
DJANGO_ALLOWED_HOSTS [] List of allowed hostnames Required
DJANGO_SETTINGS_MODULE messages.settings Django settings module Required
DJANGO_SUPERUSER_PASSWORD admin Default superuser password for development Dev
DJANGO_DATA_DIR /data Base directory for data storage Optional

Database Configuration

PostgreSQL (Main Database)

Variable Default Description Required
DATABASE_URL None Complete database URL (overrides individual DB_* vars) Optional
DB_ENGINE django.db.backends.postgresql_psycopg2 Database engine Optional
DB_HOST postgresql Database hostname (container name) Optional
DB_NAME messages Database name Optional
DB_USER user Database username Optional
DB_PASSWORD pass Database password Optional
DB_PORT 5432 Database port Optional

PostgreSQL (Keycloak)

Variable Default Description Required
POSTGRES_DB messages Keycloak database name Dev
POSTGRES_USER user Keycloak database user Dev
POSTGRES_PASSWORD pass Keycloak database password Dev

Redis Configuration

Variable Default Description Required
REDIS_URL redis://redis:6379 Redis connection URL (internal) Optional
CELERY_BROKER_URL redis://redis:6379 Celery message broker URL (internal) Optional
CACHES_DEFAULT_TIMEOUT 30 Default cache timeout in seconds Optional

Note: For external Redis access, use localhost:8913. For internal container communication, use redis:6379.

OpenSearch Configuration

Variable Default Description Required
OPENSEARCH_URL ["http://opensearch:9200"] OpenSearch hosts list Optional
OPENSEARCH_TIMEOUT 20 OpenSearch query timeout Optional
OPENSEARCH_INDEX_THREADS True Enable thread indexing Optional

Mail Processing Configuration

MTA Settings

Variable Default Description Required
MTA_OUT_MODE direct Outbound MTA mode ('direct' or 'relay') Required
MTA_OUT_RELAY_HOST mta-out:587 Outbound SMTP server host for relay mode Required
MTA_OUT_RELAY_USERNAME user Outbound SMTP username for relay mode Optional
MTA_OUT_RELAY_PASSWORD pass Outbound SMTP password for relay mode Optional
MTA_OUT_DIRECT_PROXIES [] List of SOCKS proxy URLs (randomly chosen when non-empty; used in direct mode) Optional
MTA_OUT_DIRECT_PORT 25 TCP port for direct mode on remote MX servers Optional
MTA_OUT_SMTP_TLS_SECURITY_LEVEL may SMTP TLS security level ("none", "may") Optional
MDA_API_SECRET my-shared-secret-mda Shared secret for MDA API Required
MDA_API_BASE_URL http://backend-dev:8000/api/v1.0/ Base URL for MDA API Dev

Email Domain Configuration

Variable Default Description Required
MESSAGES_TESTDOMAIN example.local Test domain for development Dev
MESSAGES_TESTDOMAIN_MAPPING_BASEDOMAIN example.com Base domain mapping Dev
MESSAGES_ACCEPT_ALL_EMAILS False Accept emails to any domain Optional

DKIM Configuration

Variable Default Description Required
MESSAGES_DKIM_SELECTOR default DKIM selector Optional
MESSAGES_DKIM_DOMAINS [] List of domains for DKIM signing Optional
MESSAGES_DKIM_PRIVATE_KEY_B64 None Base64 encoded DKIM private key Optional
MESSAGES_DKIM_PRIVATE_KEY_FILE None Path to DKIM private key file Optional

Storage Configuration

S3-Compatible Storage

Variable Default Description Required
AWS_S3_ENDPOINT_URL http://minio:9000 S3 endpoint URL Optional
AWS_S3_ACCESS_KEY_ID messages S3 access key Optional
AWS_S3_SECRET_ACCESS_KEY password S3 secret key Optional
AWS_S3_REGION_NAME None S3 region Optional
AWS_STORAGE_BUCKET_NAME st-messages-media-storage S3 bucket name Optional
AWS_S3_UPLOAD_POLICY_EXPIRATION 86400 Upload policy expiration (24h) Optional
MEDIA_BASE_URL http://localhost:8902 Base URL for media files Optional
ITEM_FILE_MAX_SIZE 5368709120 Max file size (5GB) Optional

Static Files

Variable Default Description Required
STORAGES_STATICFILES_BACKEND django.contrib.staticfiles.storage.StaticFilesStorage Static files storage backend Optional

Authentication & Authorization

OIDC Configuration

Variable Default Description Required
OIDC_CREATE_USER False Automatically create users from OIDC Optional
OIDC_RP_CLIENT_ID messages OIDC client ID Required
OIDC_RP_CLIENT_SECRET ThisIsAnExampleKeyForDevPurposeOnly OIDC client secret Required
OIDC_RP_SIGN_ALGO RS256 OIDC signing algorithm Optional
OIDC_RP_SCOPES openid email OIDC scopes Optional
OIDC_OP_JWKS_ENDPOINT http://keycloak:8000/realms/messages/protocol/openid-connect/certs OIDC JWKS endpoint Required
OIDC_OP_AUTHORIZATION_ENDPOINT http://localhost:8902/realms/messages/protocol/openid-connect/auth OIDC authorization endpoint Required
OIDC_OP_TOKEN_ENDPOINT http://keycloak:8000/realms/messages/protocol/openid-connect/token OIDC token endpoint Required
OIDC_OP_USER_ENDPOINT http://keycloak:8000/realms/messages/protocol/openid-connect/userinfo OIDC user info endpoint Required
OIDC_OP_LOGOUT_ENDPOINT None OIDC logout endpoint Optional

OIDC Advanced Settings

Variable Default Description Required
OIDC_USE_NONCE True Use nonce in OIDC flow Optional
OIDC_REDIRECT_REQUIRE_HTTPS False Require HTTPS for redirects Optional
OIDC_REDIRECT_ALLOWED_HOSTS ["http://localhost:8902", "http://localhost:8900"] Allowed redirect hosts Optional
OIDC_STORE_ID_TOKEN True Store ID token Optional
OIDC_FALLBACK_TO_EMAIL_FOR_IDENTIFICATION True Use email as fallback identifier Optional
OIDC_ALLOW_DUPLICATE_EMAILS False Allow duplicate emails (⚠️ Security risk) Optional
OIDC_AUTH_REQUEST_EXTRA_PARAMS {"acr_values": "eidas1"} Extra parameters for auth requests Optional

Authentication URLs

Variable Default Description Required
LOGIN_REDIRECT_URL http://localhost:8900 Post-login redirect URL Optional
LOGIN_REDIRECT_URL_FAILURE http://localhost:8900 Login failure redirect URL Optional
LOGOUT_REDIRECT_URL http://localhost:8900 Post-logout redirect URL Optional
ALLOW_LOGOUT_GET_METHOD True Allow GET method for logout Optional

User Mapping

Variable Default Description Required
USER_OIDC_ESSENTIAL_CLAIMS [] Essential OIDC claims Optional
USER_OIDC_FIELDS_TO_FULLNAME ["first_name", "last_name"] Fields for full name Optional
USER_OIDC_FIELD_TO_SHORTNAME first_name Field for short name Optional

Security & CORS

Variable Default Description Required
CORS_ALLOW_ALL_ORIGINS True Allow all CORS origins Optional
CORS_ALLOWED_ORIGINS [] Specific allowed CORS origins Optional
CORS_ALLOWED_ORIGIN_REGEXES [] Regex patterns for allowed origins Optional
CSRF_TRUSTED_ORIGINS ["http://localhost:8900", "http://localhost:8901"] Trusted origins for CSRF Optional
SERVER_TO_SERVER_API_TOKENS [] API tokens for server-to-server auth Optional

Monitoring & Observability

Sentry

Variable Default Description Required
SENTRY_DSN None Sentry DSN for error tracking Optional

Logging

Variable Default Description Required
LOGGING_LEVEL_LOGGERS_ROOT INFO Root logger level Optional
LOGGING_LEVEL_LOGGERS_APP INFO Application logger level Optional
LOGGING_LEVEL_HANDLERS_CONSOLE INFO Console handler level Optional

Prometheus

Variable Default Description Required
ENABLE_PROMETHEUS False Enable Prometheus monitoring Optional
PROMETHEUS_API_KEY None Bearer token required to access metrics. If unset, the endpoint is public. Set this in production. Optional

OpenAPI Schema

Variable Default Description Required
SPECTACULAR_SETTINGS_ENABLE_DJANGO_DEPLOY_CHECK False Enable deploy check in OpenAPI Optional

Frontend Configuration

Variable Default Description Required
FRONTEND_THEME dsfr Frontend theme identifier Optional
NEXT_PUBLIC_API_ORIGIN http://localhost:8901 Frontend API origin Dev
NEXT_PUBLIC_S3_DOMAIN_REPLACE http://localhost:9000 S3 domain replacement for frontend Dev
NEXT_PUBLIC_LANGUAGES [["en-US","English"],["fr-FR","Français"]] Languages available for frontend Optional
NEXT_PUBLIC_DEFAULT_LANGUAGE en-US Default language for frontend Optional

Development Tools

Crowdin (Translations)

Variable Default Description Required
CROWDIN_PERSONAL_TOKEN Your-Personal-Token Crowdin API token Dev
CROWDIN_PROJECT_ID Your-Project-Id Crowdin project ID Dev
CROWDIN_BASE_PATH /app/src Base path for translations Dev

Application Settings

Business Logic

Variable Default Description Required
TRASHBIN_CUTOFF_DAYS 30 Days before permanent deletion Optional
INVITATION_VALIDITY_DURATION 604800 Invitation validity (7 days) Optional

Model custom attributes schema

Note: Custom attributes are stored in a JSONField (Take a look at User and MailDomain models).

Variable Default Description Required
SCHEMA_CUSTOM_ATTRIBUTES_USER {} JSONSchema definition of the User custom attributes Optional
SCHEMA_CUSTOM_ATTRIBUTES_MAILDOMAIN {} JSONSchema definition of the MailDomain custom attributes Optional

Internationalization

Variable Default Description Required
LANGUAGE_CODE en-us Default backend language code Optional

AI

Variable Default Description Required
AI_BASE_URL None Default URL to access AI API endpoint (Albert API) Optional
AI_API_KEY None API Key used for AI features Optional
AI_MODEL None Default model used for AI features Optional
AI_FEATURE_SUMMARY_ENABLED False Default enabled mode for summary AI features Required
AI_FEATURE_AUTOLABELS_ENABLED False Default enabled mode for label AI features Required

External Services

Drive

Variable Default Description Required
DRIVE_BASE_URL None Base URL to access Drive endpoints Optional

Legend

  • Required: Must be set for the application to function
  • Dev: Required for development/testing environments
  • Optional: Has sensible defaults, can be customized

Environment Files

The application uses environment files located in env.d/development/ for different services:

  • backend.defaults - Main Django application settings
  • common.defaults - Shared settings across services
  • frontend.defaults - Frontend configuration
  • postgresql.defaults - PostgreSQL database configuration
  • keycloak.defaults - Keycloak configuration
  • mta-in.defaults - Inbound mail server settings
  • mta-out.defaults - Outbound mail server settings
  • crowdin.defaults - Translation service configuration

Local Overrides

The make bootstrap command creates empty .local files for each service with a comment header:

# Put your local-specific, gitignored env vars here

These files are gitignored and allow for local development customizations without affecting the repository.

Security Notes

⚠️ Important Security Considerations:

  1. Never commit actual secrets - Use .local files only
  2. OIDC_ALLOW_DUPLICATE_EMAILS - Should remain False in production
  3. CORS_ALLOW_ALL_ORIGINS - Should be False in production
  4. DJANGO_SECRET_KEY - Must be unique and secret in production
  5. Database passwords - Use strong, unique passwords
  6. API tokens - Rotate regularly and keep secure

Production Deployment

For production deployments, ensure:

  1. All Required variables are properly configured
  2. Secrets are managed through secure secret management systems
  3. HTTPS is enforced for all external communications
  4. Database connections use SSL/TLS
  5. File storage uses appropriate access controls
Reference in New Issue View Git Blame Copy Permalink