Settings

This section explains all configuration not related to authentication or storage. This includes the configuration of all dependencies that Kadi4Mat relies on, as well as other system-relevant and miscellaneous configuration.

System

SERVER_NAME

The name or IP of the host that Kadi4Mat runs on, e.g. "kadi4mat.example.edu".

Defaults to None.

Note

Note that changing this value after performing a production setup requires some changes to the generated Apache configuration file as well. Namely, the corresponding ServerName and Redirect directives need to be adapted according to the new server name. Additionally, SSL/TLS certificates might need to be updated, e.g. when using a self-signed certificate, a new one needs to be generated and configured via the SSLCertificate* directives. For generating such a certificate, or a completely new Apache configuration file, please refer back to the manual installation instructions.

SECRET_KEY

The secret key is used for most things that require encryption or signatures in Kadi4Mat, so it should be an appropriately secure value and must always be kept secret. The following command can be used to generate a suitable value:

tr -dc '[:alnum:]' < /dev/urandom | head -c20

Defaults to None.

Warning

Note that changing the secret key will invalidate all encrypted values previously stored in the database as well as all signed cookies.

MISC_UPLOADS_PATH

An absolute local file path in which all miscellaneous uploads are stored in, such as profile or group images, e.g. "/opt/kadi/uploads".

Note that the corresponding directory structure will be created automatically by the application. If you want to create it beforehand, make sure the permissions of at least the uploads directory are set up according to the user and group under which the application is running, e.g.:

sudo chown kadi:www-data /opt/kadi/uploads
sudo chmod 750 /opt/kadi/uploads

Defaults to None.

Note

Note that changing this value after performing a production setup requires some changes to the generated Apache configuration file as well. Namely, the corresponding XSendFilePath directive needs to be adapted according to the new path. Please also refer back to the manual installation instructions.

PROXY_FIX_HEADERS

This configuration option needs to be used if Kadi4Mat runs behind one or more proxy servers in order to ensure that e.g. IP addresses reported to the application cannot be easily spoofed by users via HTTP headers. This is done by specifying a dictionary in the following form:

{
    "x_for": 1,
    "x_proto": 1,
    "x_host": 0,
    "x_port": 0,
    "x_prefix": 0,
}

These values specify which HTTP headers are set by how many proxy servers. The headers that are taken into account are:

  • X-Forwarded-For, as specified via "x_for"

  • X-Forwarded-Proto, as specified via "x_proto"

  • X-Forwarded-Host, as specified via "x_host"

  • X-Forwarded-Port, as specified via "x_port"

  • X-Forwarded-Prefix, as specified via "x_prefix"

Note that when following along with the installation instructions in this documentation, the default value should not be changed.

Defaults to None.

EXPERIMENTAL_FEATURES

Enable experimental features, which may not yet be stable, fully tested and/or feature complete.

Defaults to False.

WORKFLOW_FEATURES

Enable all workflow features that are stable enough to not be classified as experimental anymore. Note that these features might still not be complete in various ways, but enabling and using them should not lead to any issues.

Defaults to False. If EXPERIMENTAL_FEATURES is True, this flag will automatically be set to True as well.

Note

This is a temporary flag that will be removed again once all workflow-related functionality is fully usable via Kadi4Mat’s web interface.

Dependencies

SQLALCHEMY_DATABASE_URI

The database connection string to use for PostgreSQL in the form of postgresql://<user>:<password>@<host>/<database>. The database user (<user>) and database name (<database>) will generally be kadi, while the password (<password>) of the database user is chosen when creating the database user. In single-machine setups, the host (<host>) is usually just localhost. If the used port differs from the default value (5432), it can be specified after the host as <host>:<port>.

Defaults to None.

ELASTICSEARCH_HOSTS; ELASTICSEARCH_CONFIG

The connection configuration to use for Elasticsearch. ELASTICSEARCH_HOSTS can either be a single value or a list of values specifying one or more Elasticsearch nodes to connect to. ELASTICSEARCH_CONFIG can be used to further customize the connection parameters in form of a dictionary, whose contents will be passed to the client instance of elasticsearch-py.

In particular, these values will need to be changed when running Elasticsearch on a different machine/port and using SSL/TLS as well as some form of authentication, especially when using a more intricate setup than a simple, single-node deployment.

Defaults to "http://localhost:9200" and {"timeout": 15}.

CELERY_BROKER_URL

The connection string to use for the Celery broker that communicates between Kadi4Mat and the Celery workers. Using Redis is recommended, which can be specified in the form of redis://<user>:<password>@<host>:<port>/<db>.

This value only needs to be changed when running Redis on a different machine/port and using authentication or when using another Redis database. Note that it should be no problem to use the same Redis connection as for RATELIMIT_STORAGE_URI.

Defaults to "redis://localhost:6379/0".

Emails

SMTP_HOST; SMTP_PORT; SMTP_USERNAME; SMTP_PASSWORD; SMTP_USE_TLS; SMTP_TIMEOUT

These values specify the SMTP connection needed to send emails via Kadi4Mat, most importantly the SMTP host (SMTP_HOST) and port (SMTP_PORT). If the SMTP server requires authentication, the username and password can be specified using SMTP_USERNAME and SMTP_PASSWORD. If SMTP_USE_TLS is enabled, STARTTLS will be used for an encrypted SMTP connection. Finally, SMTP_TIMEOUT specifies the timeout in seconds when connecting to the SMTP server.

Defaults to "localhost" (host), 25 (port), "" (username), "" (password), True (encryption) and 60 (timeout).

Tip

Sysadmins can also test the sending of emails via the graphical sysadmin interface.

MAIL_NO_REPLY

The email address that will be used to send no-reply emails from, e.g. for confirming email addresses or password reset requests for local accounts.

Defaults to "no-reply@<fqdn>", where <fqdn> is the fully qualified domain name of the server.

MAIL_SUBJECT_HEADER

A header value to be included in the subject field of all emails sent by the application. The header and subject values are combined in the form of [<MAIL_SUBJECT_HEADER>] <subject>.

Defaults to "Kadi4Mat".

MAIL_ERROR_LOGS

A list of email addresses that will receive logs of unexpected/uncaught errors and exceptions using Python’s SMTPHandler. As this will send an email for each individual error, setting up Sentry via SENTRY_DSN may be the preferred way for error monitoring.

Defaults to [].

Rate limiting

RATELIMIT_STORAGE_URI

The connection string to use for caching information used for rate limiting. Using Redis is recommended, which can be specified in the form of redis://<user>:<password>@<host>:<port>/<db>.

This value only needs to be changed when running Redis on a different machine/port and using authentication or when using another Redis database. Note that it should be no problem to use the same Redis connection as for CELERY_BROKER_URL.

Defaults to "redis://localhost:6379/0".

RATELIMIT_ANONYMOUS_USER

The global default rate limit for unauthenticated users. Must be a limit string according to the specification of the Flask-Limiter library. Specifying an empty string ("") will disable this limit altogether.

Defaults to "90/minute;3/second".

Tip

For more complex rate limiting needs, see also how to develop plugins and the kadi.plugins.spec.kadi_get_default_rate_limit() plugin hook.

RATELIMIT_AUTHENTICATED_USER

The global default rate limit for authenticated users. Must be a limit string according to the specification of the Flask-Limiter library. Specifying an empty string ("") will disable this limit altogether.

Defaults to "".

Tip

For more complex rate limiting needs, see also how to develop plugins and the kadi.plugins.spec.kadi_get_default_rate_limit() plugin hook.

RATELIMIT_IP_WHITELIST

A list of IP addresses that are exempt from rate limiting.

Defaults to ["127.0.0.1"].

Customization

BROADCAST_MESSAGE

Markdown formatted text shown at the top of all pages to all authenticated users. Users are able to dismiss a broadcast message, however, it will reappear whenever its content is changed.

Can also be set via the graphical sysadmin interface.

Defaults to "".

BROADCAST_MESSAGE_PUBLIC

Whether to show the broadcast message to unauthenticated users as well.

Can also be set via the graphical sysadmin interface.

Defaults to False.

A list of additional navigation items, which are shown on all pages in the footer next to the existing items. Each item consists of a list containing its title and an absolute or relative URL, e.g.:

NAV_FOOTER_ITEMS = [
   ["My Link", "https://example.com"],
]

Can also be set via the graphical sysadmin interface.

Defaults to [].

Tip

For more complex customization needs, see also how to develop plugins and the kadi.plugins.spec.kadi_get_nav_footer_items() plugin hook.

INDEX_IMAGE

An absolute path to a JPEG or PNG image file, which will be shown on the index page next to the INDEX_TEXT.

Can also be set via the graphical sysadmin interface.

Defaults to None.

Tip

For more complex customization needs, see also how to develop plugins and the kadi.plugins.spec.kadi_get_index_templates() plugin hook.

INDEX_TEXT

Markdown formatted text, which will be shown on the index page next to the INDEX_IMAGE.

Can also be set via the graphical sysadmin interface.

Defaults to "".

Tip

For more complex customization needs, see also how to develop plugins and the kadi.plugins.spec.kadi_get_index_templates() plugin hook.

Legals

TERMS_OF_USE

Markdown formatted text to specify terms of use. Once set, the terms of use are available on a separate page (/terms-of-use). A corresponding shortcut to this page is automatically created in the navigation footer.

Can also be set via the graphical sysadmin interface.

Defaults to "".

PRIVACY_POLICY

Markdown formatted text to specify a privacy policy. Once set, the privacy policy is available on a separate page (/privacy-policy). A corresponding shortcut to this page is automatically created in the navigation footer.

Can also be set via the graphical sysadmin interface.

Defaults to "".

ENFORCE_LEGALS

Require all users to accept the terms of use and/or privacy policy, if at least one of them is configured and whenever one of them is changed. If registration of new local users is enabled, a corresponding checkbox will be shown in the registration form to accept the configured legal notices. Users which had their account created via different means, as well as existing users, will be prompted to accept the configured or updated legal notices on their next Kadi4Mat interaction instead.

Can also be set via the graphical sysadmin interface.

Defaults to False.

Note

Note that due to technical limitations, changes to one of the enforced legal notices are only tracked when specifying them via the graphical sysadmin interface, i.e. only in this case existing users are required to accept them again.

Markdown formatted text to specify a legal notice. Once set, the legal notice is available on a separate page (/legal-notice). A corresponding shortcut to this page is automatically created in the navigation footer.

Can also be set via the graphical sysadmin interface.

Defaults to "".

Miscellaneous

ROBOTS_NOINDEX

Exclude a public Kadi4Mat instance from being indexed by search engines. This applies to the entire website, including all outgoing links. When set retroactively, it might take a while until existing results are deleted from the various search indices.

Note that some web crawlers might not recognize this option, but it should work for all major search engines.

Can also be set via the graphical sysadmin interface.

Defaults to False.

SENTRY_DSN

A Sentry DSN (Data Source Name) which can be used to integrate the Sentry error monitoring tool with Kadi4Mat.

Note

Note that in production setups, the uWSGI configuration file might need to be adapted for the Flask integration of Sentry to work properly. Please also refer back to the manual installation instructions.

Defaults to None.

Plugins

PLUGINS; PLUGIN_CONFIG

These values are used to enable and configure plugins. See the Plugins section for more information.

Defaults to [] and {}.