Platform Configuration
Overview
Platform Configuration covers the mechanisms operators use to configure Open edX platform behavior — site-level settings, feature flags (waffle flags/switches), course-level overrides, Django admin, and configuration management. This is the control panel for platform behavior without code changes.
Open edX has a layered configuration system: environment variables and `lms.yml`/`cms.yml` files for infrastructure settings, Django admin for dynamic runtime configuration, and waffle flags for per-feature/per-user rollout.
Current State (2026)
• Waffle flags: Django Waffle flags and switches control feature rollout; `edx-toggles` standardizes how toggles are annotated and documented
• Site configuration: `SiteConfiguration` model in `edx-platform` Django admin allows per-site overrides of settings
• Django admin: The primary configuration UI; extensive use for user management, course configuration, feature toggles
• LMS/CMS YAML: Infrastructure-level settings in `lms.yml` and `cms.yml` (or environment variables); managed by Tutor or custom deployment
• Admin console MFE: `frontend-app-admin-console` provides a more modern UI for some admin functions
Architecture
• Django admin: Auto-generated from models; heavily used for site configuration, user roles, course overrides
• Waffle: `edx-toggles` wraps Django Waffle; all toggles annotated with ownership and expected lifetime
• `SiteConfiguration`: Key-value store scoped to a site (django-sites framework); allows per-instance overrides without code changes
• Config models: `django-config-models` provides configuration models with history, caching, and admin UI
• Tutor: In Tutor deployments, most config managed via Tutor config variables and plugins; generates YAML files
History
Origin
• Year introduced: 2012–2013 (configuration via Django settings from the start)
• Initial implementation: Django settings files (Python) for all configuration; Django admin for runtime overrides
• Context: Standard Django configuration pattern; as the platform grew, dynamic configuration without deployments became important
Key Milestones
Django settings-based configuration
Waffle flags introduced for feature rollout
`SiteConfiguration` model for per-site overrides
`edx-toggles` standardizes toggle annotation
Open Questions
- ?When were waffle flags first introduced and what drove that decision?
- ?How does `SiteConfiguration` relate to Django's sites framework?
- ?How do Tutor config variables map to Django settings?
- ?What are the most common configuration mistakes operators make?
- ?How is configuration migrated between environments (dev → staging → production)?