Skip to main content

Key addons (legacy)

Aldryn Django (core Django)​

info

Aldryn continues to be supported by Divio, but we do not recommend using Aldryn Django for new applications.

Aldryn Django (aldryn-django) is a wrapper application that installs and provides basic configuration for Django.

See aldryn-django.aldryn_config (ensure that you switch to the correct branch) for the all settings it takes and how they are applied.

Most of the key settings are listed below.

Control Panel options​

Some settings are exposed in the Aldryn Addon configuration form in the Control Panel. These settings will take priority over those entered as environment variables or in settings.py.

Hash static file names​

The Aldryn Django addon includes a Hash static file names option. When selected, Django's ManifestStaticFilesStorage will be used as the storage backend. This appends an MD5 hash of each file's contents to its filename, allowing caching headers to be safely set in the far future.

Aldryn Django configures uWSGI to set the Cache-Control header to one year on files with a hash in the filename.

Enable django.contrib.gis​

Enables GeoDjango support. Adds django.contrib.gis to INSTALLED_APPS and sets the database engine to django.contrib.gis.db.backends.postgis.

For local development you will need to edit docker-compose.yml, changing postgres:15.7-alpine to mdillon/postgis:15.7-alpine. On the cloud, you will need to make a support request to have the new database enabled for the application.

See Manage Postgres extensions for more details.

Remove URL language prefix for default language​

When set, will add aldryn_django.middleware.LanguagePrefixFallbackMiddleware to the middleware.

This will cause Django not to use a language prefix in the URL when serving the default language. For example, by default, /about will redirect to /en/about if English is the default language; with this option selected, it will not (and will instead redirect in the other direction).

Note that prior to Django version 1.10, this will not work with applications in which multiple languages are defined.

This is a 302 Temporary Redirect, as determined in Django's core. It is not safe to use permanent redirects here, because language redirects are content-dependent. A change in the site could cause redirect loops, as described at 301 Permanent vs 302 Temporary redirects, or spurious 404 errors.

Timeout for users session, in seconds​

See SESSION_COOKIE_AGE in Session middleware settings.

Environment variable/settings.py options​

Security middleware settings​

Each of these settings can be specified as an environment variable (recommended except where indicated otherwise below) or in settings.py. These settings apply to Django's Security middleware.

Session middleware settings​

DOMAIN_REDIRECTS​

A list of domain names that will redirect to the site's primary domain name.

By default, this is populated by the Control Panel. If required, it can also be specified as an environment variable on the Live server (recommended) or in settings.py.

Setting this manually will allow you to add the internal Divio domain of the site, such as example.eu.aldryn.io, to the domains that will redirect to the primary domain. (You may wish to do this if you don't want users or search engines to discover your site at example.eu.aldryn.io rather than example.com.)

warning

Note that if you specify DOMAIN_REDIRECTS manually, you will need to list all the secondary domains you want to handle, as it overrides the setting automatically generated by the Control Panel.

ALDRYN_SITES_REDIRECT_PERMANENT​

By default, redirects are 302 Temporary Redirect. When True, redirects (where this is appropriate) will be 301 Permanent Redirect.

Can be specified as an environment variable (recommended) or in settings.py.

See 301 Permanent vs 302 Temporary redirects for more information.

Storage settings​

Cache control for static files​

Static files in our Django applications are collected by Django at build time, and served by uWSGI. Aldryn Django configures the command it issues to uWSGI to start static file serving on the basis of application settings. By default, files are served with no Cache-Control header applied.

STATICFILES_DEFAULT_MAX_AGE​

The STATICFILES_DEFAULT_MAX_AGE determines the Cache-Control header value that uWSGI will use for unhashed files (see the Hash static file names option, above). It is not recommended to set this to high values, as the cached versions can continue to be used even after files themselves have been updated.

DISABLE_S3_MEDIA_HEADERS_UPDATE​

Applications using Aldryn Django will update media file headers by running:

python manage.py aldryn_update_s3_media_headers

as a release command; this can be controlled with the DISABLE_S3_MEDIA_HEADERS_UPDATE environment variable. The aldryn_update_s3_media_headers command can cause excessively long deployment times on very large media buckets, so setting this variable to True can avoid that.

Django server settings​

See notes on DJANGO_WEB_WORKERS, DJANGO_WEB_MAX_REQUESTS, DJANGO_WEB_TIMEOUT in How to fine-tune your server's performance.

Email settings​

See Sending email in Divio applications for details of available settings.

Miscellaneous settings​

  • DISABLE_GZIP determines whether Django's GZipMiddleware will be added to the application's middleware (default: False)
  • TIME_ZONE (default: the appropriate time zone for your server cloudspace)
  • SENTRY_DSN - if provided, logging to Sentry will be configured automatically

Aldryn SSO (authentication)​

info

Aldryn continues to be supported by Divio, but we do not recommend using Aldryn Django for new applications.

Authentication to the Divio platform, and (by default) to user applications running on the platform, is handled by the Divio SSO (single-sign-on) system. This provides a convenient way to authenticate users for Divio applications (whether locally, or on the Test or Live servers) without needing to log in again, as long as they have logged into the Divio Control Panel.

This includes making it possible for users working on applications locally to log in locally with a single click, as they have already been authenticated.

Divio SSO is managed by the open-source Aldryn SSO addon. The system is optional, but is installed by default in all Divio Django applications.

If the addon is uninstalled, then Django's standard authentication behaviour will apply.

Login methods​

The Aldryn SSO addon provides three different login methods to Divio applications:

Illustration of Divio application login options

Depending on how the application is configured, and which environment (local/test/live) it's running in, different combinations of these options will be shown (you'll never see all three at once in a real application).

The illustrated options are:

1. Local development login​

This is intended to appear on locally-running applications only. The Add user option is a convenient way to add new users to an application.

See ALDRYN_SSO_ENABLE_LOCALDEV.

2. Django's standard username/password login form​

This will not be of any use unless users with passwords exist in the database.

See ALDRYN_SSO_ENABLE_LOGIN_FORM.

3. Divio single-sign-on​

This is intended to appear on applications running in Cloud environments only. It allows users to sign in to their own applications with a single click, once they have authenticated with the Divio control panel.

See ALDRYN_SSO_ENABLE_SSO_LOGIN.

Test site protection​

By default the Test site is protected so that it's not publicly discoverable or viewable. Only the owner or an authorised user of the application can view its contents.

This is controlled with the ALDRYN_SSO_ALWAYS_REQUIRE_LOGIN environment variable, which is True by default and can be overridden by setting it manually.

See also how to apply/remove password protection to Django sites.

Aldryn SSO configuration options​

important

The preferred way to set these options is as environment variables.

If you supply them as Django settings declared in settings.py, they must appear before aldryn_addons.settings.load(locals()). This allows them to be processed correctly by the addons system.

The exception is ALDRYN_SSO_HIDE_USER_MANAGEMENT, which is configured via the Control Panel, or by adding the variable after aldryn_addons.settings.load(locals()).

More details of how Aldryn SSO processes these settings can be studied at aldryn-sso.aldryn_config.py.

ALDRYN_SSO_ALWAYS_REQUIRE_LOGIN​

Controls whether visitors need to be logged-in. Available options are:

  • True: Users will need to log in via the SSO system in order to access the site (default for test site).
  • False: No login is required (default for local and live environments).
  • basicauth: The site will be protected by basic HTML access authorisation. See basicauth.

Can also be specified as an environment variable or in settings.py.

ALDRYN_SSO_ENABLE_LOCALDEV​

Enables Local development login.

When True (default for the local environment only) enables the Add user pane in the login form, providing a convenient way to add a new user to the database.

Can also be specified as an environment variable or in settings.py.

warning

For obvious reasons, enabling this is strongly not recommended on the Test and Live sites, and there is generally no good reason to manipulate this setting.

ALDRYN_SSO_ENABLE_SSO_LOGIN​

Enables single-sign-on.

Requires a value to be present in SSO_DSN, and is automatically set when there is. If enabled when no SSO_DSN value has been set, an error will be raised.

Can also be specified as an environment variable or in settings.py.

ALDRYN_SSO_ENABLE_LOGIN_FORM​

Enables Django's standard username/password login form.

By default, is enabled when Hide user management is not enabled.

Can also be specified as an environment variable or in settings.py.

ALDRYN_SSO_ENABLE_AUTO_SSO_LOGIN​

When True (the default on all sites) then if SSO login is the only login method enabled, the user will be automatically logged-in via SSO (assuming of course that the user is authorised to do so).

The logic for this condition is:

====================================  =========
ALDRYN_SSO_ENABLE_SSO_LOGIN           True
ALDRYN_SSO_ENABLE_AUTO_SSO_LOGIN      True
ALDRYN_SSO_ENABLE_LOGIN_FORM          False
ALDRYN_SSO_ENABLE_LOCALDEV            False
====================================  =========

Can also be specified as an environment variable or in settings.py.

ALDRYN_SSO_HIDE_USER_MANAGEMENT​

This option is presented in the configuration form for the Aldryn SSO addon on the Control Panel (as Hide user management). Its effect is to unregister the User and Group models in the Django admin.

Setting it as an environment variable will have no effect.

Specifying it in settings.py will only have an effect if it is declared after aldryn_addons.settings.load(locals()). This is not recommended except for testing purposes.

For local testing, the hide_user_management value in aldryn-addons/aldryn-sso/settings.json can be changed, mimicking the effect of the form value.

Basic access authentication​

Basic access authentication is configured using ALDRYN_SSO_BASICAUTH_USER and ALDRYN_SSO_BASICAUTH_PASSWORD.

When ALDRYN_SSO_ALWAYS_REQUIRE_LOGIN is set to basicauth, access to the entire site will require user and password details. This is an additional layer of authentication. Access to the admin will still require login by an admin user, and even a logged-in admin user will need to supply the username and password.

See also

Basic access authentication.

Though the username and password can be specified as an environment variable or in settings.py, the latter is not good practice.

SSO_DSN​

The Data Source Name for single-sign-on.

This is set as an environment variable automatically in Cloud applications, adding the SSO authority to the URL configuration for the application.

If you are providing your own single-sign-on, SSO_DSN can also be specified as an environment variable or in settings.py.

LOGIN_REDIRECT_URL​

After login, redirect to the specified URL (by default, to /).

Specifying LOGIN_REDIRECT_URL in settings.py will only have an effect if it is declared after aldryn_addons.settings.load(locals()).

ALDRYN_SSO_LOGIN_WHITE_LIST​

A list of internal endpoints that don't require authentication. Defaults to an empty list.

For example:

from django.core.urlresolvers import reverse_lazy

ALDRYN_SSO_LOGIN_WHITE_LIST = [reverse_lazy('my_whitelisted_endpoint')]

Can be specified as an environment variable or in settings.py, or manipulated programmatically in other applications:

if 'ALDRYN_SSO_LOGIN_WHITE_LIST' in settings:

    settings['ALDRYN_SSO_LOGIN_WHITE_LIST'].extend([reverse_lazy('my_whitelisted_endpoint')])

ALDRYN_SSO_OVERRIDE_ADMIN_LOGIN_VIEW​

We override Django's admin login view by default, as long as one of the three login options is enabled. This takes better care of logged-in users who are not staff (admin) users.

The standard Django administration login view is available by setting this to False as an environment variable or in settings.py.

Aldryn Addons (addon integration)​

info

Aldryn continues to be supported by Divio, but we do not recommend using Aldryn Django for new applications.

The Aldryn Addons framework helps integrate addons and their settings into a Django application.

It's an open-source package, and is itself an addon. The addons framework is installed by default in all Divio Cloud Django applications.

Aldryn Addons configuration options​

Addon URLs​

An application, or an addon in it, may need to specify some URL patterns.

They could simply be added to the application's urls.py manually. However, it's also convenient for addons to be able to configure URLs programmatically, so that when an addon is installed, it will also take care of setting up the relevant URL configurations.

Aldryn Addons provides a way to do this. A Divio application's urls.py contains:

urlpatterns = [
    # add your own patterns here
] + aldryn_addons.urls.patterns() + i18n_patterns(
    # add your own i18n patterns here
    *aldryn_addons.urls.i18n_patterns()  # MUST be the last entry!
)

As well as indicated places for manually-added patterns, it calls aldryn_addons.urls.patterns() and aldryn_addons.urls.i18n_patterns().

These functions, in the urls.py of Aldryn Addons, check for and return the values in four different settings:

ADDON_URLS and ADDON_URLS_I18N​

These are expected to be lists of URL patterns. Each addon that needs to add its own URL patterns should add them to the lists.

For example, in Aldryn django CMS:

settings['ADDON_URLS'].append('aldryn_django_cms.urls')
ADDON_URLS_LAST and ADDON_URLS_I18N_LAST​

These are not lists, and only one of each can be set in any application - it's not possible for two applications both to specify an ADDON_URLS_I18N_LAST for example.

django CMS sets settings['ADDON_URLS_I18N_LAST'] = 'cms.urls' - so in an application using django CMS, no other application can use ADDON_URLS_I18N_LAST.