Settings#
This is the list of (non-toggle) Django settings defined in the common.py modules of edx-platform.
Note
Toggle settings, which enable or disable a specific feature, are documented in the feature toggles section.
LMS settings#
ACCOUNT_MICROFRONTEND_URL#
Default: None
Source: common.py (line 5001)
Base URL of the micro-frontend-based account settings page.
Warning
Also set site’s ENABLE_ACCOUNT_MICROFRONTEND and account.redirect_to_microfrontend waffle flag
BLOCKSTORE_BUNDLE_CACHE_TIMEOUT#
Default: 3000
Source: common.py (line 5194)
Maximum time-to-live of cached Bundles fetched from Blockstore, in seconds. When the values returned from Blockstore have TTLs of their own (such as signed S3 URLs), the maximum TTL of this cache must be lower than the minimum TTL of those values. We use a default of 3000s (50mins) because temporary URLs are often configured to expire after one hour.
BLOCK_STRUCTURES_SETTINGS#
Default: "dict of settings"
Source: common.py (line 2940)
Stores all the settings used by block structures and block structure related tasks. See BLOCK_STRUCTURES_SETTINGS[XXX] documentation for details of each setting. For more information, check https://github.com/openedx/edx-platform/pull/13388.
BLOCK_STRUCTURES_SETTINGS[‘COURSE_PUBLISH_TASK_DELAY’]#
Default: 30
Source: common.py (line 2946)
Delay, in seconds, after a new edit of a course is published before updating the block structures cache. This is needed for a better chance at getting the latest changes when there are secondary reads in sharded mongoDB clusters. For more information, check https://github.com/openedx/edx-platform/pull/13388 and https://github.com/openedx/edx-platform/pull/14571.
BLOCK_STRUCTURES_SETTINGS[‘TASK_DEFAULT_RETRY_DELAY’]#
Default: 30
Source: common.py (line 2955)
Delay, in seconds, between retry attempts if a block structure task fails. For more information, check https://github.com/openedx/edx-platform/pull/13388 and https://github.com/openedx/edx-platform/pull/14571.
BLOCK_STRUCTURES_SETTINGS[‘TASK_MAX_RETRIES’]#
Default: 5
Source: common.py (line 2962)
Maximum number of retries per block structure task. If the maximum number of retries is exceeded, then you can attempt to either manually run the celery task, or wait for it to be triggered again. For more information, check https://github.com/openedx/edx-platform/pull/13388 and https://github.com/openedx/edx-platform/pull/14571.
BUNDLE_ASSET_STORAGE_SETTINGS#
Default: "dict, appropriate for file system storage."
Source: common.py (line 5222)
When this is set, `BUNDLE_ASSET_URL_STORAGE_KEY` is
BUNDLE_ASSET_URL_STORAGE_KEY#
Default: None
Source: common.py (line 5204)
When this is set, `BUNDLE_ASSET_URL_STORAGE_SECRET` is
BUNDLE_ASSET_URL_STORAGE_SECRET#
Default: None
Source: common.py (line 5213)
When this is set, `BUNDLE_ASSET_URL_STORAGE_KEY` is
CCX_MAX_STUDENTS_ALLOWED#
Default: 200
Source: common.py (line 4490)
Maximum number of students allowed in a CCX (Custom Courses for edX), This is an arbitrary hard limit, chosen so that a CCX does not compete with public MOOCs.
CELERY_EXTRA_IMPORTS#
Default: "[]"
Source: common.py (line 2843)
Adds extra packages that don’t get auto-imported (Example: XBlocks). These packages are added in addition to those added by CELERY_IMPORTS.
CODE_JAIL_REST_SERVICE_CONNECT_TIMEOUT#
Default: 0.5
Source: common.py (line 1859)
Set the number of seconds LMS will wait to establish an internal connection to the codejail remote service.
CODE_JAIL_REST_SERVICE_HOST#
Default: "'http://127.0.0.1:8550'"
Source: common.py (line 1855)
Set the codejail remote service host
CODE_JAIL_REST_SERVICE_READ_TIMEOUT#
Default: 3.5
Source: common.py (line 1863)
Set the number of seconds LMS will wait for a response from the codejail remote service endpoint.
CODE_JAIL_REST_SERVICE_REMOTE_EXEC#
Default: "'xmodule.capa.safe_exec.remote_exec.send_safe_exec_request_v0'"
Source: common.py (line 1850)
Set the python package.module.function that is reponsible of calling the remote service in charge of jailed code execution
COMPREHENSIVE_THEME_DIRS#
Default: "[]"
Source: common.py (line 4547)
A list of directories containing themes folders, each entry should be a full path to the directory containing the theme folder.
COMPREHENSIVE_THEME_LOCALE_PATHS#
Default: "[]"
Source: common.py (line 4553)
A list of the paths to themes locale directories e.g. “COMPREHENSIVE_THEME_LOCALE_PATHS” : [“/edx/src/edx-themes/conf/locale”].
COURSE_MEMBER_API_ENROLLMENT_LIMIT#
Default: 1000
Source: common.py (line 4364)
This limits the response size of the `get_course_members` API, throwing an exception if the number of Enrolled users is greater than this number. This is needed to limit the dataset size since the API does most of the calculation in Python to avoid expensive database queries.
CUSTOM_RESOURCE_TEMPLATES_DIRECTORY#
Default: None
Source: common.py (line 4584)
Path to an existing directory of YAML files containing html content to be used with the subclasses of xmodule.x_module.ResourceTemplates. Default example templates can be found in xmodule/templates/html. Note that the extension used is “.yaml” and not “.yml”. See xmodule.x_module.ResourceTemplates for usage. “CUSTOM_RESOURCE_TEMPLATES_DIRECTORY” : null
DEFAULT_SITE_THEME#
Default: None
Source: common.py (line 4566)
Theme to use when no site or site theme is defined, for example “dark-theme”. Set to None if you want to use openedx default theme.
Warning
The theme folder needs to be in ‘edx-platform/themes’ or define the path to the theme folder in COMPREHENSIVE_THEME_DIRS. To be effective, ENABLE_COMPREHENSIVE_THEMING has to be enabled.
DISCUSSIONS_MFE_FEEDBACK_URL#
Default: None
Source: common.py (line 5033)
Base URL of the discussions micro-frontend google form based feedback.
DISCUSSIONS_MICROFRONTEND_URL#
Default: None
Source: common.py (line 5028)
Base URL of the micro-frontend-based discussions page.
Warning
Also set site’s courseware.discussions_mfe waffle flag.
EDXNOTES_CLIENT_NAME#
Default: "edx-notes"
Source: common.py (line 2178)
Set the name of the Oauth client used by LMS to authenticate with the edx_notes_api service.
Warning
The Oauth client must be created in the platform Django admin in the path /admin/oauth2_provider/application/, setting the name field of the client as the value of this setting.
EDXNOTES_CONNECT_TIMEOUT#
Default: 0.5
Source: common.py (line 2186)
Set the number of seconds LMS will wait to establish an internal connection to the edx_notes_api service.
EDXNOTES_INTERNAL_API#
Default: "http://localhost:18120/api/v1"
Source: common.py (line 2169)
Set the internal API endpoint LMS will use in the backend to interact with the edx_notes_api service.
Warning
Normally set to the same value of EDXNOTES_PUBLIC_API. It is not mandatory for this setting to be a publicly accessible endpoint, but to be accessible by the LMS service. It is only used when the setting FEATURES[‘ENABLE_EDXNOTES’] is activated.
EDXNOTES_PUBLIC_API#
Default: "http://localhost:18120/api/v1"
Source: common.py (line 2161)
Set the public API endpoint LMS will use in the frontend to interact with the edx_notes_api service.
Warning
This setting must be a publicly accessible endpoint. It is only used when the setting FEATURES[‘ENABLE_EDXNOTES’] is activated.
EDXNOTES_READ_TIMEOUT#
Default: 1.5
Source: common.py (line 2190)
Set the number of seconds LMS will wait for a response from the edx_notes_api service internal endpoint.
ELASTIC_SEARCH_INDEX_PREFIX#
Default: "''"
Source: common.py (line 1464)
Specifies the prefix used when namixng elasticsearch indexes related to edx-search.
EVENT_BUS_PRODUCER_CONFIG#
Default: "all events disabled"
Source: common.py (line 5447)
Dictionary of event_types mapped to dictionaries of topic to topic-related configuration. Each topic configuration dictionary contains * `enabled`: a toggle denoting whether the event will be published to the topic. These should be annotated according to https://edx.readthedocs.io/projects/edx-toggles/en/latest/how_to/documenting_new_feature_toggles.html * `event_key_field` which is a period-delimited string path to event data field to use as event key. Note: The topic names should not include environment prefix as it will be dynamically added based on EVENT_BUS_TOPIC_PREFIX setting.
EXAMS_DASHBOARD_MICROFRONTEND_URL#
Default: None
Source: common.py (line 5037)
Base URL of the exams dashboard micro-frontend for instructors.
LEARNING_MICROFRONTEND_URL#
Default: None
Source: common.py (line 5010)
Base URL of the micro-frontend-based courseware page.
LOGIN_REDIRECT_WHITELIST#
Default: "empty list ([])"
Source: common.py (line 3680)
While logout, if logout request has a redirect-url as query strings, then the redirect-url is validated through LOGIN_REDIRECT_WHITELIST.
MAINTENANCE_BANNER_TEXT#
Default: "'Sample banner message'"
Source: common.py (line 1495)
Specifies the text that is rendered on the maintenance banner.
Warning
Depends on the `open_edx_util.display_maintenance_warning` waffle switch. The banner is only rendered when the switch is activated.
MAX_FAILED_LOGIN_ATTEMPTS_ALLOWED#
Default: 6
Source: common.py (line 3810)
Specifies the maximum failed login attempts allowed to users. Once the user reaches this failure threshold then the account will be locked for a configurable amount of seconds (30 minutes) which will prevent additional login attempts until this time period has passed. This setting is related with MAX_FAILED_LOGIN_ATTEMPTS_LOCKOUT_PERIOD_SECS and only used when ENABLE_MAX_FAILED_LOGIN_ATTEMPTS is enabled.
MAX_FAILED_LOGIN_ATTEMPTS_LOCKOUT_PERIOD_SECS#
Default: "30 * 60"
Source: common.py (line 3819)
Specifies the lockout period in seconds for consecutive failed login attempts. Once the user reaches the threshold of the login failure, then the account will be locked for the given amount of seconds (30 minutes) which will prevent additional login attempts until this time period has passed. This setting is related with MAX_FAILED_LOGIN_ATTEMPTS_ALLOWED and only used when ENABLE_MAX_FAILED_LOGIN_ATTEMPTS is enabled.
MFE_CONFIG#
Default: "{}"
Source: common.py (line 5348)
Is a configuration that will be exposed by the MFE Config API to be consumed by the MFEs. Contains configuration common to all MFEs. When a specific MFE’s configuration is requested, these values will be treated as a base and then overriden/supplemented by those in `MFE_CONFIG_OVERRIDES`. Example: { “BASE_URL”: “https://name_of_mfe.example.com”, “LANGUAGE_PREFERENCE_COOKIE_NAME”: “example-language-preference”, “CREDENTIALS_BASE_URL”: “https://credentials.example.com”, “DISCOVERY_API_BASE_URL”: “https://discovery.example.com”, “LMS_BASE_URL”: “https://courses.example.com”, “LOGIN_URL”: “https://courses.example.com/login”, “LOGOUT_URL”: “https://courses.example.com/logout”, “STUDIO_BASE_URL”: “https://studio.example.com”, “LOGO_URL”: “https://courses.example.com/logo.png” }
MFE_CONFIG_API_CACHE_TIMEOUT#
Default: "60*5"
Source: common.py (line 5388)
The MFE Config API response will be cached during the specified time
MFE_CONFIG_OVERRIDES#
Default: "{}"
Source: common.py (line 5369)
Overrides or additions to `MFE_CONFIG` for when a specific MFE is requested by the MFE Config API. Top-level keys are APP_IDs, a.k.a. the name of the MFE (for example, for an MFE named “frontend-app-xyz”, the top-level key would be “xyz”). Example: { “gradebook”: { “BASE_URL”: “https://gradebook.example.com”, }, “profile”: { “BASE_URL”: “https://profile.example.com”, “ENABLE_LEARNER_RECORD_MFE”: “true”, }, }
ORA_GRADING_MICROFRONTEND_URL#
Default: None
Source: common.py (line 5014)
Base URL of the micro-frontend-based openassessment grading page. This is will be show in the open response tab list data.
Warning
Also set site’s openresponseassessment.enhanced_staff_grader waffle flag.
ORA_MICROFRONTEND_URL#
Default: None
Source: common.py (line 5021)
Base URL for modern openassessment app. This is will be show in the open response tab list data.
Warning
Also set site’s openresponseassessment.mfe_views waffle flag.
PLATFORM_NAME#
Default: "Your Platform Name Here"
Source: common.py (line 71)
The display name of the platform to be used in templates/emails/etc.
PREPEND_LOCALE_PATHS#
Default: "[]"
Source: common.py (line 4560)
A list of the paths to locale directories to load first e.g. “PREPEND_LOCALE_PATHS” : [“/edx/my-locales/”].
PROFILE_MICROFRONTEND_URL#
Default: None
Source: common.py (line 4994)
Base URL of the micro-frontend-based profile page.
Warning
Also set site’s ENABLE_PROFILE_MICROFRONTEND and learner_profile.redirect_to_microfrontend waffle flag
RATELIMIT_RATE#
Default: "120/m"
Source: common.py (line 4856)
Due to some reports about attack on /oauth2/access_token/ which took LMS down, this setting was introduced to rate-limit all endpoints of AccessTokenView up to 120 requests per IP Address in a minute by default.
Warning
RATELIMIT_ENABLE flag must also be enabled/set to True to use this RATELIMIT_RATE setting.
REGISTRATION_EXTRA_FIELDS#
Default: "{'confirm_email': 'hidden', 'level_of_education': 'optional', 'gender': 'optional',
'year_of_birth': 'optional', 'mailing_address': 'optional', 'goals': 'optional', 'honor_code': 'required',
'terms_of_service': 'hidden', 'city': 'hidden', 'country': 'hidden'}"
Source: common.py (line 3688)
The signup form may contain extra fields that are presented to every user. For every field, we can specifiy whether it should be “required”: to display the field, and make it mandatory; “optional”: to display the optional field as part of a toggled input field list; “optional-exposed”: to display the optional fields among the required fields, and make it non-mandatory; “hidden”: to not display the field. When the terms of service are not visible and agreement to the honor code is required (the default), the signup page includes a paragraph that links to the honor code page (defined my MKTG_URLS[“HONOR”]). This page might not be available for all Open edX platforms. In such cases, the “honor_code” registration field should be “hidden”.
REGISTRATION_RATELIMIT#
Default: "60/7d"
Source: common.py (line 3441)
New users are registered on edx via RegistrationView. It’s POST end-point is rate-limited up to 60 requests per IP Address in a week by default. Purpose of this setting is to restrict an attacker from registering numerous fake accounts.
REGISTRATION_VALIDATION_RATELIMIT#
Default: "30/7d"
Source: common.py (line 3432)
Whenever a user tries to register on edx, the data entered during registration is validated via RegistrationValidationView. It’s POST endpoint is rate-limited up to 30 requests per IP Address in a week by default. It was introduced because an attacker can guess or brute force a series of names to enumerate valid users.
RETIRED_EMAIL_DOMAIN#
Default: "retired.invalid"
Source: common.py (line 4901)
Set the domain part of hashed emails for retired users. Used by the derived setting RETIRED_EMAIL_FMT.
RETIRED_EMAIL_FMT#
Default: "retired__user_{}@retired.invalid"
Source: common.py (line 4912)
Set the format a retired user email field gets transformed into, where {} is replaced with the hash of the original email. This is a derived setting that depends on RETIRED_EMAIL_PREFIX and RETIRED_EMAIL_DOMAIN values.
RETIRED_EMAIL_PREFIX#
Default: "retired__user_"
Source: common.py (line 4896)
Set the prefix part of hashed emails for retired users. Used by the derived setting RETIRED_EMAIL_FMT.
RETIRED_USERNAME_FMT#
Default: "retired__user_{}"
Source: common.py (line 4906)
Set the format a retired user username field gets transformed into, where {} is replaced with the hash of the original username. This is a derived setting that depends on RETIRED_USERNAME_PREFIX value.
RETIRED_USERNAME_PREFIX#
Default: "retired__user_"
Source: common.py (line 4890)
Set the prefix part of hashed usernames for retired users. Used by the derived setting RETIRED_USERNAME_FMT.
RETIRED_USER_SALTS#
Default: "['abc', '123']"
Source: common.py (line 4919)
Set a list of salts used for hashing usernames and emails on users retirement.
Warning
Only the last item in this list is used as a salt for all new retirements, but historical salts are preserved in order to guarantee that all hashed usernames and emails can still be checked.
RETIREMENT_SERVICE_WORKER_USERNAME#
Default: "RETIREMENT_SERVICE_USER"
Source: common.py (line 4926)
Set the username of the retirement service worker user. Retirement scripts authenticate with LMS as this user with oauth client credentials.
RETIREMENT_STATES#
Default: "[
'PENDING',
'LOCKING_ACCOUNT',
'LOCKING_COMPLETE',
'RETIRING_FORUMS',
'FORUMS_COMPLETE',
'RETIRING_EMAIL_LISTS',
'EMAIL_LISTS_COMPLETE',
'RETIRING_ENROLLMENTS',
'ENROLLMENTS_COMPLETE',
'RETIRING_NOTES',
'NOTES_COMPLETE',
'RETIRING_LMS',
'LMS_COMPLETE',
'ERRORED',
'ABORTED',
'COMPLETE',
]"
Source: common.py (line 4932)
Set a list that defines the name and order of states for the retirement workflow.
Warning
These states are stored in the database and it is the responsibility of the administrator to populate the state list since the states can vary across different installations. There must be, at minimum, a PENDING state at the beginning, and COMPLETED, ERRORED, and ABORTED states at the end of the list.
SECURITY_PAGE_URL#
Default: None
Source: common.py (line 3491)
A link to the site’s security disclosure/reporting policy, to display in the site footer. This will only appear for sites using themes that use the links produced by ``lms.djangoapps.branding.api.get_footer``.
SURVEY_REPORT_CHECK_THRESHOLD#
Default: "every 6 months"
Source: common.py (line 5546)
Survey report banner will appear if a survey report is not sent in the months defined.
SURVEY_REPORT_ENDPOINT#
Default: "Open edX organization endpoint"
Source: common.py (line 5535)
Endpoint where the report will be sent.
SURVEY_REPORT_EXTRA_DATA#
Default: "empty dictionary"
Source: common.py (line 5550)
Dictionary with additional information that you want to share in the report.
XBLOCK_EXTRA_MIXINS#
Default: "()"
Source: common.py (line 1675)
Custom mixins that will be dynamically added to every XBlock and XBlockAside instance. These can be classes or dotted-path references to classes. For example: `XBLOCK_EXTRA_MIXINS = (‘my_custom_package.my_module.MyCustomMixin’,)`
XBLOCK_FIELD_DATA_WRAPPERS#
Default: "()"
Source: common.py (line 1682)
Paths to wrapper methods which should be applied to every XBlock’s FieldData.
XBLOCK_RUNTIME_V2_EPHEMERAL_DATA_CACHE#
Default: "default"
Source: common.py (line 5189)
The django cache key of the cache to use for storing anonymous user state for XBlocks.
XBLOCK_SETTINGS#
Default: "{}"
Source: common.py (line 1690)
Dictionary containing server-wide configuration of XBlocks on a per-type basis. By default, keys should match the XBlock `block_settings_key` attribute/property. If the attribute/property is not defined, use the XBlock class name. Check `xmodule.services.SettingsService` for more reference.
CMS settings#
BLOCKSTORE_BUNDLE_CACHE_TIMEOUT#
Default: 3000
Source: common.py (line 2674)
Maximum time-to-live of cached Bundles fetched from Blockstore, in seconds. When the values returned from Blockstore have TTLs of their own (such as signed S3 URLs), the maximum TTL of this cache must be lower than the minimum TTL of those values. We use a default of 3000s (50mins) because temporary URLs are often configured to expire after one hour.
CODE_JAIL_REST_SERVICE_CONNECT_TIMEOUT#
Default: 0.5
Source: common.py (line 1203)
Set the number of seconds CMS will wait to establish an internal connection to the codejail remote service.
CODE_JAIL_REST_SERVICE_HOST#
Default: "'http://127.0.0.1:8550'"
Source: common.py (line 1199)
Set the codejail remote service host
CODE_JAIL_REST_SERVICE_READ_TIMEOUT#
Default: 3.5
Source: common.py (line 1207)
Set the number of seconds CMS will wait for a response from the codejail remote service endpoint.
CODE_JAIL_REST_SERVICE_REMOTE_EXEC#
Default: "'xmodule.capa.safe_exec.remote_exec.send_safe_exec_request_v0'"
Source: common.py (line 1194)
Set the python package.module.function that is reponsible of calling the remote service in charge of jailed code execution
COMPREHENSIVE_THEME_DIRS#
Default: "[]"
Source: common.py (line 2181)
See LMS annotation.
COMPREHENSIVE_THEME_LOCALE_PATHS#
Default: "[]"
Source: common.py (line 2186)
See LMS annotation. “COMPREHENSIVE_THEME_LOCALE_PATHS” : [“/edx/src/edx-themes/conf/locale”].
COURSEGRAPH_CONNECTION#
Default: "'bolt+s://localhost:7687', in dictionary form."
Source: common.py (line 2437)
Dictionary specifying Neo4j connection parameters for CourseGraph refresh. Accepted keys are protocol (‘bolt’ or ‘http’), secure (bool), host (str), port (int), user (str), and password (str). See https://py2neo.org/2021.1/profiles.html#individual-settings for a a description of each of those keys.
COURSEGRAPH_JOB_QUEUE#
Default: "value of LOW_PRIORITY_QUEUE"
Source: common.py (line 2431)
The name of the Celery queue to which CourseGraph refresh tasks will be sent
CUSTOM_RESOURCE_TEMPLATES_DIRECTORY#
Default: None
Source: common.py (line 2211)
Path to an existing directory of YAML files containing html content to be used with the subclasses of xmodule.x_module.ResourceTemplates. Default example templates can be found in xmodule/templates/html. Note that the extension used is “.yaml” and not “.yml”. See xmodule.x_module.ResourceTemplates for usage. “CUSTOM_RESOURCE_TEMPLATES_DIRECTORY” : null
DEFAULT_SITE_THEME#
Default: None
Source: common.py (line 2198)
See LMS annotation.
EVENT_BUS_PRODUCER_CONFIG#
Default: "all events disabled"
Source: common.py (line 2855)
Dictionary of event_types mapped to dictionaries of topic to topic-related configuration. Each topic configuration dictionary contains * `enabled`: a toggle denoting whether the event will be published to the topic. These should be annotated according to https://edx.readthedocs.io/projects/edx-toggles/en/latest/how_to/documenting_new_feature_toggles.html * `event_key_field` which is a period-delimited string path to event data field to use as event key. Note: The topic names should not include environment prefix as it will be dynamically added based on EVENT_BUS_TOPIC_PREFIX setting.
GIT_EXPORT_DEFAULT_IDENT#
Default: "{'name': 'STUDIO_EXPORT_TO_GIT', 'email': 'STUDIO_EXPORT_TO_GIT@example.com'}"
Source: common.py (line 1246)
When courses are exported to git, commits are signed with this name/email git identity.
GIT_REPO_EXPORT_DIR#
Default: "'/edx/var/edxapp/export_course_repos'"
Source: common.py (line 1240)
When courses are exported to git, either with the export_git management command or the git export view from the studio (when FEATURES[‘ENABLE_EXPORT_GIT’] is True), they are stored in this directory, which must exist at the time of the export.
PREPEND_LOCALE_PATHS#
Default: "[]"
Source: common.py (line 2192)
A list of the paths to locale directories to load first e.g. “PREPEND_LOCALE_PATHS” : [“/edx/my-locales/”].
STUDIO_NAME#
Default: "Your Platform Studio"
Source: common.py (line 178)
The name that will appear on the landing page of Studio, as well as in various emails and templates.
XBLOCK_EXTRA_MIXINS#
Default: "()"
Source: common.py (line 1017)
Custom mixins that will be dynamically added to every XBlock and XBlockAside instance. These can be classes or dotted-path references to classes. For example: `XBLOCK_EXTRA_MIXINS = (‘my_custom_package.my_module.MyCustomMixin’,)`