From eba4d5779e31ca86dc332fc97e72f6e5c9a66791 Mon Sep 17 00:00:00 2001 From: Jochen Klar Date: Thu, 17 Oct 2024 19:44:21 +0200 Subject: [PATCH 1/2] Add settings page --- docs/configuration/index.md | 7 +- docs/configuration/settings.md | 652 +++++++++++++++++++++++++++++++++ 2 files changed, 657 insertions(+), 2 deletions(-) create mode 100644 docs/configuration/settings.md diff --git a/docs/configuration/index.md b/docs/configuration/index.md index 871865e..7d7937e 100644 --- a/docs/configuration/index.md +++ b/docs/configuration/index.md @@ -5,8 +5,10 @@ The RDMO application uses the [Django settings](https://docs.djangoproject.com/e ``` config/settings/local.py ``` -This `local.py` module is copied from the template `config/settings/sample.local.py`, contained in the `rdmo-app`, during the installation process. The module is ignored by git and is meant to contain your local adjustments and secret information (e.g. database connections). -The `config/settings/local.py` module can be used to override all of the default settings of RDMO (see: [rdmo/core/settings.py](https://github.com/rdmorganiser/rdmo/blob/main/rdmo/core/settings.py)). + +This `local.py` module is copied from the template `config/settings/sample.local.py`, contained in the `rdmo-app`, during the installation process. The module is ignored by git and is meant to contain your local adjustments and secret information (e.g. database connections). + +In principle, the `config/settings/local.py` module can be used to override all of the default settings of RDMO. A complete description of settings relevant for RDMO is given in [here](./settings). --- @@ -22,4 +24,5 @@ cache logging projects multisite +settings ``` diff --git a/docs/configuration/settings.md b/docs/configuration/settings.md new file mode 100644 index 0000000..f3f426b --- /dev/null +++ b/docs/configuration/settings.md @@ -0,0 +1,652 @@ +Settings +======== + +RDMO can be customised using various settings. Since RDMO is based on Django, we use its [build-in settings system](https://docs.djangoproject.com/en/stable/topics/settings/). Almost every setting has a default value, which is set in the RDMO packacge in [rdmo/core/settings.py](https://github.com/rdmorganiser/rdmo/blob/main/rdmo/core/settings.py). + +In the following all settings, which can be changed from their default values to customize you particular RDMO instance are described in detail. + +--- + +#### SECRET_KEY + +Secret key for RDMO. This is used to provide cryptographic signing, and should be set to a unique, unpredictable value (e.g. from a password generator). + +See also [SECRET_KEY](https://docs.djangoproject.com/en/stable/ref/settings/#std:setting-SECRET_KEY) in the Django documentation. Should be set in `.env`. + +--- + +#### DEBUG + +Default: `False` + +Debug mode. See also [DEBUG](https://docs.djangoproject.com/en/stable/ref/settings/#std:setting-DEBUG) in the Django documentation. Should **never** set to `True` in production. + +--- + +#### ALLOWED_HOSTS + +Default: `[]` + +List of allowed hosts for this app. If your instance runs under `https://rdmo.example.com` the list needs to contain `rdmo.example.com`. + +See also [ALLOWED_HOSTS](https://docs.djangoproject.com/en/stable/ref/settings/#std:setting-ALLOWED_HOSTS) in the Django documentation. + +--- + +#### INSTALLED_APPS + +The list of Django apps for this RDMO instance. By default, it contains the main Django apps, the RDMO apps from the RDMO package and some 3rd party packages. A theme and or plugins need to be added to this list when used, e.g.: + +```python +from . import INSTALLED_APPS +INSTALLED_APPS += ['rdmo_theme', 'rdmo_plugin'] +``` + +See also [INSTALLED_APPS](https://docs.djangoproject.com/en/stable/ref/settings/#std:setting-INSTALLED_APPS) in the Django documentation. + +--- + +#### AUTHENTICATION_BACKENDS + +Default: + +```python +[ + 'rules.permissions.ObjectPermissionBackend', + 'django.contrib.auth.backends.ModelBackend' +] +``` + +--- + +#### MULTISITE + +Default: `False` + +--- + +#### GROUPS + +Default: `False` + +--- + +#### LOGIN_FORM + +Default: `True` + +--- + +#### PROFILE_UPDATE + +Default: `True` + +--- + +#### PROFILE_DELETE + +Default: `True` + +--- + +#### ACCOUNT + +Default: `False` + +--- + +#### ACCOUNT_SIGNUP + +Default: `False` + +--- + +#### ACCOUNT_GROUPS + +Default: `[]` + +--- + +#### ACCOUNT_TERMS_OF_USE + +Default: `False` + +--- + +#### ACCOUNT_ACTIVATION_DAYS + +Default: `7` + +--- + +#### ACCOUNT_EMAIL_CONFIRMATION_EXPIRE_DAYS + +Default: `7` + +--- + +#### ACCOUNT_EMAIL_VERIFICATION + +Default: `'optional'` + +--- + +#### ACCOUNT_USERNAME_MIN_LENGTH + +Default: `4` + +--- + +#### ACCOUNT_PASSWORD_MIN_LENGTH + +Default: `4` + +--- + +#### ACCOUNT_ALLOW_USER_TOKEN + +Default: `False` + +--- + +#### SOCIALACCOUNT + +Default: `False` + +--- + +#### SOCIALACCOUNT_SIGNUP + +Default: `False` + +--- + +#### SOCIALACCOUNT_GROUPS + +Default: `[]` + +--- + +#### SHIBBOLETH + +Default: `False` + +--- + +#### SHIBBOLETH_LOGIN_URL + +Default: `'/Shibboleth.sso/Login'` + +--- + +#### SHIBBOLETH_LOGOUT_URL + +Default: `'/Shibboleth.sso/Logout'` + +--- + +#### SHIBBOLETH_USERNAME_PATTERN + +Default: `None` + +--- + +#### LANGUAGE_CODE + +Default: `'en-us'` + +--- + +#### TIME_ZONE + +Default: `'Europe/Berlin'` + +--- + +#### LANGUAGES + +Default: + +```python +( + ('en', _('English')), + ('de', _('German')), +) +``` + +--- + +#### DATABASES + +Default: + +``` +{ + 'default': { + 'ENGINE': 'django.db.backends.sqlite3', + 'NAME': 'db.sqlite3' + } +} +``` + +--- + +#### EMAIL_BACKEND + +Default: `'django.core.mail.backends.console.EmailBackend'` + +--- + +#### DEFAULT_FROM_EMAIL + +Default: `'info@example.com'` + +--- + +#### EMAIL_RECIPIENTS_CHOICES + +Default: `[]` + +--- + +#### EMAIL_RECIPIENTS_INPUT + +Default: `False` + +--- + +#### USER_API + +Default: `True` + +--- + +#### OVERLAYS + +Default: + +```python +{ + 'projects': [ + 'projects-table', + 'create-project', + 'import-project', + 'support-info' + ], + 'project': [ + 'project-questions', + 'project-catalog', + 'project-issues', + 'project-views', + 'project-memberships', + 'project-snapshots', + 'export-project', + 'import-project', + 'support-info' + ], + 'issue_send': [ + 'issue-message', + 'issue-attachments', + 'support-info' + ] +} +``` + +--- + +#### EXPORT_FORMATS + +Default: + +```python +( + ('pdf', _('PDF')), + ('rtf', _('Rich Text Format')), + ('odt', _('Open Office')), + ('docx', _('Microsoft Office')), + ('html', _('HTML')), + ('markdown', _('Markdown')), + ('mediawiki', _('mediawiki')), + ('tex', _('LaTeX')) +) +``` + +--- + +#### EXPORT_REFERENCE_ODT_VIEWS + +Default `{}` + +--- + +#### EXPORT_REFERENCE_DOCX_VIEWS + +Default `{}` + +--- + +#### EXPORT_REFERENCE_ODT + +Default: `None` + +--- + +#### EXPORT_REFERENCE_DOCX + +Default: `None` + +--- + +#### EXPORT_PANDOC_ARGS + +Default: + +```python +{ + 'pdf': ['-V', 'geometry:a4paper, margin=1in', '--pdf-engine=xelatex'], + 'rtf': ['--standalone'] +} +``` + +--- + +#### EXPORT_CONTENT_DISPOSITION + +Default `'attachment'` + +--- + +#### PROJECT_TABLE_PAGE_SIZE + +Default: `20` + +--- + +#### PROJECT_ISSUES + +Default: `True` + +--- + +#### PROJECT_ISSUE_PROVIDERS + +Default: `[]` + +--- + +#### PROJECT_VIEWS + +Default: `True` + +--- + +#### PROJECT_EXPORTS + +Default: + +```python +[ + ('xml', _('RDMO XML'), 'rdmo.projects.exports.RDMOXMLExport'), + ('csvcomma', _('CSV (comma separated)'), 'rdmo.projects.exports.CSVCommaExport'), + ('csvsemicolon', _('CSV (semicolon separated)'), 'rdmo.projects.exports.CSVSemicolonExport'), + ('json', _('JSON'), 'rdmo.projects.exports.JSONExport'), +] +``` + +--- + +#### PROJECT_SNAPSHOT_EXPORTS + +Default: `[]` + +--- + +#### PROJECT_IMPORTS + +Default: `[]` + +```python +[ + ('xml', _('RDMO XML'), 'rdmo.projects.imports.RDMOXMLImport'), +] +``` + +--- + +#### PROJECT_IMPORTS_LIST + +Default: `[]` + +--- + +#### PROJECT_QUESTIONS_AUTOSAVE + +Default: `True` + +--- + +#### PROJECT_QUESTIONS_CYCLE_SETS + +Default: `False` + +--- + +#### PROJECT_FILE_QUOTA + +Default: `'10Mb'` + +--- + +#### PROJECT_SEND_ISSUE + +Default: `False` + +--- + +#### PROJECT_INVITE_TIMEOUT + +Default: `None` + +--- + +#### PROJECT_SEND_INVITE + +Default: `True` + +--- + +#### PROJECT_REMOVE_VIEWS + +Default: `True` + +--- + +#### PROJECT_CREATE_RESTRICTED + +Default: `False` + +--- + +#### PROJECT_CREATE_GROUPS + +Default: `[]` + +--- + +#### PROJECT_VALUES_CONFLICT_THRESHOLD + +Default: `0.01` + +--- + +#### NESTED_PROJECTS + +Default: `True` + +--- + +#### OPTIONSET_PROVIDERS + +Default: `[]` + +--- + +#### PROJECT_VALUES_VALIDATION + +Default: `False` + +--- + +#### PROJECT_VALUES_VALIDATION_URL + +Default: `True` + +--- + +#### PROJECT_VALUES_VALIDATION_INTEGER + +Default: `True` + +--- + +#### PROJECT_VALUES_VALIDATION_INTEGER_MESSAGE + +Default: `_('Enter a valid integer.')` + +--- + +#### PROJECT_VALUES_VALIDATION_INTEGER_REGEX + +Default: `re.compile(r'^[+-]?\d+$')` + +--- + +#### PROJECT_VALUES_VALIDATION_FLOAT + +Default: `True` + +--- + +#### PROJECT_VALUES_VALIDATION_FLOAT_MESSAGE + +Default: `_('Enter a valid float.')` + +--- + +#### PROJECT_VALUES_VALIDATION_FLOAT_REGEX + +Default: + +```python +re.compile(r''' + ^[+-]? # Optional sign + ( + \d+ # Digits before the decimal or thousands separator + (,\d{3})* # Optional groups of exactly three digits preceded by a comma (thousands separator) + (\.\d+)? # Optional decimal part, a dot followed by one or more digits + | # OR + \d+ # Digits before the decimal or thousands separator + (\.\d{3})* # Optional groups of exactly three digits preceded by a dot (thousands separator) + (,\d+)? # Optional decimal part, a comma followed by one or more digits + ) + ([eE][+-]?\d+)?$ # Optional exponent part +''', re.VERBOSE) +``` + +--- + +#### PROJECT_VALUES_VALIDATION_BOOLEAN + +Default: `True` + +--- + +#### PROJECT_VALUES_VALIDATION_BOOLEAN_MESSAGE + +Default: `_('Enter a valid boolean (e.g. 0, 1).')` + +--- + +#### PROJECT_VALUES_VALIDATION_BOOLEAN_REGEX + +Default: `r'(?i)^(0|1|f|t|false|true)$'` + +--- + +#### PROJECT_VALUES_VALIDATION_DATE + +Default: `True` + +--- + +#### PROJECT_VALUES_VALIDATION_DATE_MESSAGE + +Default: `_('Enter a valid date (e.g. "02.03.2024", "03/02/2024", "2024-02-03").')` + +--- + +#### PROJECT_VALUES_VALIDATION_DATE_REGEX + +Default: + +```python +re.compile(r''' + ^( + \d{1,2}\.\s*\d{1,2}\.\s*\d{2,4} # Format dd.mm.yyyy + | \d{1,2}/\d{1,2}/\d{4} # Format mm/dd/yyyy + | \d{4}-\d{2}-\d{2} # Format yyyy-mm-dd + )$ +''', re.VERBOSE) +``` + +--- + +#### PROJECT_VALUES_VALIDATION_DATETIME + +Default: `True` + +--- + +#### PROJECT_VALUES_VALIDATION_EMAIL + +Default: `True` + +--- + +#### PROJECT_VALUES_VALIDATION_PHONE + +Default: `True` + +--- + +#### PROJECT_VALUES_VALIDATION_PHONE_MESSAGE + +Default: `_('Enter a valid phone number (e.g. "123456" or "+49 (0) 30 123456").')` + +--- + +#### PROJECT_VALUES_VALIDATION_PHONE_REGEX + +Default: + +```python +re.compile(r''' + ^([+]\d{2,3}\s)? # Optional country code + (\(\d+\)\s)? # Optional area code in parentheses + [\d\s]*$ # Main number with spaces +''', re.VERBOSE) +``` + +--- + +#### DEFAULT_URI_PREFIX + +Default: `'http://example.com/terms'` + +--- + +#### REPLACE_MISSING_TRANSLATION + +Default: `False` + +--- \ No newline at end of file From 456058631b771d0ea18dea57859c8af007a14b41 Mon Sep 17 00:00:00 2001 From: Jochen Klar Date: Thu, 31 Oct 2024 14:53:35 +0100 Subject: [PATCH 2/2] Update LDAP settings --- docs/configuration/authentication/ldap.md | 41 +++++++++++++++++++++-- 1 file changed, 39 insertions(+), 2 deletions(-) diff --git a/docs/configuration/authentication/ldap.md b/docs/configuration/authentication/ldap.md index 0e67698..1a0e4b3 100644 --- a/docs/configuration/authentication/ldap.md +++ b/docs/configuration/authentication/ldap.md @@ -1,5 +1,7 @@ # LDAP +## Prerequisites + In order to use a LDAP backend with RDMO you need to install some prerequistes. On Debian/Ubuntu you can install them using: ```bash @@ -31,7 +33,9 @@ userPassword: RDMO_LDAP_ACCOUNT_PASSWORD and end with a blank line followed by `ctrl-d`. -Then, in your `config/settings/local.py` add or uncomment: +## Configuration + +In order to use LDAP as one of your authentication backends in RDMO, edit `config/settings/local.py` and add or uncomment: ```python import ldap @@ -63,7 +67,40 @@ The connection can be tested using: ldapsearch -v -x -H 'ldap://ldap.example.com' -D "uid=rdmo,dc=ldap,dc=example,dc=com" -w RDMO_LDAP_ACCOUNT_PASSWORD -b "dc=ldap,dc=example,dc=com" -s sub 'uid=user' ``` -The setting `PROFILE_UPDATE = False` and `PROFILE_DELETE = False` tell RDMO to disable the update and deletion form for the user profile so that users can neither update their credentials nor delete their profile anymore. The other settings are needed by `django-auth-ldap` and are described in the [django-auth-ldap documentation](https://django-auth-ldap.readthedocs.io/en/latest/). +The setting `PROFILE_UPDATE = False` and `PROFILE_DELETE = False` tell RDMO to disable the update and deletion form for the user profile so that users can neither update their credentials nor delete their profile anymore. + +The other settings are needed by `django-auth-ldap` and are described in the [django-auth-ldap documentation](https://django-auth-ldap.readthedocs.io/en/latest/). + +For an LDAP connection to an Active Directory, the configuration differs slightly: + +```python +import ldap +from django_auth_ldap.config import LDAPSearch + +PROFILE_UPDATE = False +PROFILE_DELETE = False + +AUTH_LDAP_SERVER_URI = "ldap://ldap.example.com" +AUTH_LDAP_BIND_DN = "cn=RDMO_LDAP_ACCOUNT_CN,dc=ldap,dc=example,dc=com" +AUTH_LDAP_BIND_PASSWORD = "RDMO_LDAP_ACCOUNT_PASSWORD" +AUTH_LDAP_USER_SEARCH = LDAPSearch("dc=ldap,dc=example,dc=com", ldap.SCOPE_SUBTREE, "(sAMAccountName=%(user)s)") +AUTH_LDAP_CONNECTION_OPTIONS = {ldap.OPT_REFERRALS: 0} + +AUTH_LDAP_USER_ATTR_MAP = { + "first_name": "givenName", + "last_name": "sn", + 'email': 'mail' +} + +AUTHENTICATION_BACKENDS.insert( + AUTHENTICATION_BACKENDS.index('django.contrib.auth.backends.ModelBackend'), + 'django_auth_ldap.backend.LDAPBackend' +) +``` + +Again, your particular setup might differ. + +## Groups You can also map LDAP groups to Django groups, in particular to restrict the access to Catalogs and Views. This can be done by adding the following settings: