Settings#

Warning

Be careful when you override settings, especially when the default value is a non-empty list or dictionary, such as STATICFILES_FINDERS. Make sure you keep the components required by the features of GingerDJ you wish to use.

Core Settings #

Here’s a list of settings available in GingerDJ core and their default values. Settings provided by contrib apps are listed below, followed by a topical index of the core settings. For introductory material, see the settings topic guide.

`ABSOLUTE_URL_OVERRIDES`#

Default: {} (Empty dictionary)

A dictionary mapping "app_label.model_name" strings to functions that take a model object and return its URL. This is a way of inserting or overriding get_absolute_url() methods on a per-installation basis. Example:

ABSOLUTE_URL_OVERRIDES = {
    "blogs.blog": lambda o: "/blogs/%s/" % o.slug,
    "news.story": lambda o: "/stories/%s/%s/" % (o.pub_year, o.slug),
}

The model name used in this setting should be all lowercase, regardless of the case of the actual model class name.

`ADMINS`#

Default: [] (Empty list)

A list of all the people who get code error notifications. When DEBUG=False and AdminEmailHandler is configured in LOGGING (done by default), GingerDJ emails these people the details of exceptions raised in the request/response cycle.

Each item in the list should be a tuple of (Full name, email address). Example:

[("John", "john@example.com"), ("Mary", "mary@example.com")]

`ALLOWED_HOSTS`#

Default: [] (Empty list)

A list of strings representing the host/domain names that this GingerDJ site can serve. This is a security measure to prevent HTTP Host header attacks, which are possible even under many seemingly-safe web server configurations.

Values in this list can be fully qualified names (e.g. 'www.example.com'), in which case they will be matched against the request’s Host header exactly (case-insensitive, not including port). A value beginning with a period can be used as a subdomain wildcard: '.example.com' will match example.com, www.example.com, and any other subdomain of example.com. A value of '*' will match anything; in this case you are responsible to provide your own validation of the Host header (perhaps in a middleware; if so this middleware must be listed first in MIDDLEWARE).

GingerDJ also allows the fully qualified domain name (FQDN) of any entries. Some browsers include a trailing dot in the Host header which GingerDJ strips when performing host validation.

If the Host header (or X-Forwarded-Host if USE_X_FORWARDED_HOST is enabled) does not match any value in this list, the gingerdj.http.HttpRequest.get_host() method will raise SuspiciousOperation.

When DEBUG is True and ALLOWED_HOSTS is empty, the host is validated against ['.localhost', '127.0.0.1', '[::1]'].

ALLOWED_HOSTS is also checked when running tests.

This validation only applies via get_host(); if your code accesses the Host header directly from request.META you are bypassing this security protection.

`APPEND_SLASH`#

Default: True

When set to True, if the request URL does not match any of the patterns in the URLconf and it doesn’t end in a slash, an HTTP redirect is issued to the same URL with a slash appended. Note that the redirect may cause any data submitted in a POST request to be lost.

The APPEND_SLASH setting is only used if CommonMiddleware is installed (see Middleware). See also PREPEND_WWW.

`CACHES`#

Default:

{
    "default": {
        "BACKEND": "gingerdj.core.cache.backends.locmem.LocMemCache",
    }
}

A dictionary containing the settings for all caches to be used with GingerDJ. It is a nested dictionary whose contents maps cache aliases to a dictionary containing the options for an individual cache.

The CACHES setting must configure a default cache; any number of additional caches may also be specified. If you are using a cache backend other than the local memory cache, or you need to define multiple caches, other options will be required. The following cache options are available.

`BACKEND`#

Default: '' (Empty string)

The cache backend to use. The built-in cache backends are:

'gingerdj.core.cache.backends.db.DatabaseCache'
'gingerdj.core.cache.backends.dummy.DummyCache'
'gingerdj.core.cache.backends.filebased.FileBasedCache'
'gingerdj.core.cache.backends.locmem.LocMemCache'
'gingerdj.core.cache.backends.memcached.PyMemcacheCache'
'gingerdj.core.cache.backends.memcached.PyLibMCCache'
'gingerdj.core.cache.backends.redis.RedisCache'

You can use a cache backend that doesn’t ship with GingerDJ by setting BACKEND to a fully-qualified path of a cache backend class (i.e. mypackage.backends.whatever.WhateverCache).

`KEY_FUNCTION`#

A string containing a dotted path to a function (or any callable) that defines how to compose a prefix, version and key into a final cache key. The default implementation is equivalent to the function:

def make_key(key, key_prefix, version):
    return ":".join([key_prefix, str(version), key])

You may use any key function you want, as long as it has the same argument signature.

See the cache documentation for more information.

`KEY_PREFIX`#

Default: '' (Empty string)

A string that will be automatically included (prepended by default) to all cache keys used by the GingerDJ server.

See the cache documentation for more information.

`LOCATION`#

Default: '' (Empty string)

The location of the cache to use. This might be the directory for a file system cache, a host and port for a memcache server, or an identifying name for a local memory cache. e.g.:

CACHES = {
    "default": {
        "BACKEND": "gingerdj.core.cache.backends.filebased.FileBasedCache",
        "LOCATION": "/var/tmp/ginger_cache",
    }
}

`OPTIONS`#

Default: None

Extra parameters to pass to the cache backend. Available parameters vary depending on your cache backend.

Some information on available parameters can be found in the cache arguments documentation. For more information, consult your backend module’s own documentation.

`TIMEOUT`#

Default: 300

The number of seconds before a cache entry is considered stale. If the value of this setting is None, cache entries will not expire. A value of 0 causes keys to immediately expire (effectively “don’t cache”).

`VERSION`#

Default: 1

The default version number for cache keys generated by the GingerDJ server.

See the cache documentation for more information.

`CACHE_MIDDLEWARE_ALIAS`#

Default: 'default'

The cache connection to use for the cache middleware.

`CACHE_MIDDLEWARE_KEY_PREFIX`#

Default: '' (Empty string)

A string which will be prefixed to the cache keys generated by the cache middleware. This prefix is combined with the KEY_PREFIX setting; it does not replace it.

See GingerDJ’s cache framework.

`CACHE_MIDDLEWARE_SECONDS`#

Default: 600

The default integer number of seconds to cache a page for the cache middleware.

See GingerDJ’s cache framework.

`CSRF_USE_SESSIONS`#

Default: False

Whether to store the CSRF token in the user’s session instead of in a cookie. It requires the use of gingerdj.contrib.sessions.

Storing the CSRF token in a cookie (GingerDJ’s default) is safe, but storing it in the session is common practice in other web frameworks and therefore sometimes demanded by security auditors.

Since the default error views require the CSRF token, SessionMiddleware must appear in MIDDLEWARE before any middleware that may raise an exception to trigger an error view (such as PermissionDenied) if you’re using CSRF_USE_SESSIONS. See Middleware ordering.

`CSRF_FAILURE_VIEW`#

Default: 'gingerdj.views.csrf.csrf_failure'

A dotted path to the view function to be used when an incoming request is rejected by the CSRF protection. The function should have this signature:

def csrf_failure(request, reason=""): ...

where reason is a short message (intended for developers or logging, not for end users) indicating the reason the request was rejected. It should return an HttpResponseForbidden.

gingerdj.views.csrf.csrf_failure() accepts an additional template_name parameter that defaults to '403_csrf.html'. If a template with that name exists, it will be used to render the page.

`CSRF_HEADER_NAME`#

Default: 'HTTP_X_CSRFTOKEN'

The name of the request header used for CSRF authentication.

As with other HTTP headers in request.META, the header name received from the server is normalized by converting all characters to uppercase, replacing any hyphens with underscores, and adding an 'HTTP_' prefix to the name. For example, if your client sends a 'X-XSRF-TOKEN' header, the setting should be 'HTTP_X_XSRF_TOKEN'.

`CSRF_TRUSTED_ORIGINS`#

Default: [] (Empty list)

A list of trusted origins for unsafe requests (e.g. POST).

For requests that include the Origin header, GingerDJ’s CSRF protection requires that header match the origin present in the Host header.

For a secure unsafe request that doesn’t include the Origin header, the request must have a Referer header that matches the origin present in the Host header.

These checks prevent, for example, a POST request from subdomain.example.com from succeeding against api.example.com. If you need cross-origin unsafe requests, continuing the example, add 'https://subdomain.example.com' to this list (and/or http://... if requests originate from an insecure page).

The setting also supports subdomains, so you could add 'https://*.example.com', for example, to allow access from all subdomains of example.com.

`DATABASES`#

Default: {} (Empty dictionary)

A dictionary containing the settings for all databases to be used with GingerDJ. It is a nested dictionary whose contents map a database alias to a dictionary containing the options for an individual database.

The DATABASES setting must configure a default database; any number of additional databases may also be specified.

The simplest possible settings file is for a single-database setup using SQLite. This can be configured using the following:

DATABASES = {
    "default": {
        "ENGINE": "gingerdj.db.backends.sqlite3",
        "NAME": "mydatabase",
    }
}

When connecting to other database backends, such as MariaDB, MySQL, Oracle, or PostgreSQL, additional connection parameters will be required. See the ENGINE setting below on how to specify other database types. This example is for PostgreSQL:

DATABASES = {
    "default": {
        "ENGINE": "gingerdj.db.backends.postgresql",
        "NAME": "mydatabase",
        "USER": "mydatabaseuser",
        "PASSWORD": "mypassword",
        "HOST": "127.0.0.1",
        "PORT": "5432",
    }
}

The following inner options that may be required for more complex configurations are available:

`ATOMIC_REQUESTS`#

Default: False

Set this to True to wrap each view in a transaction on this database. See Tying transactions to HTTP requests.

`AUTOCOMMIT`#

Default: True

Set this to False if you want to disable GingerDJ’s transaction management and implement your own.

`ENGINE`#

Default: '' (Empty string)

The database backend to use. The built-in database backends are:

'gingerdj.db.backends.postgresql'
'gingerdj.db.backends.mysql'
'gingerdj.db.backends.sqlite3'
'gingerdj.db.backends.oracle'

You can use a database backend that doesn’t ship with GingerDJ by setting ENGINE to a fully-qualified path (i.e. mypackage.backends.whatever).

`HOST`#

Default: '' (Empty string)

Which host to use when connecting to the database. An empty string means localhost. Not used with SQLite.

If this value starts with a forward slash ('/') and you’re using MySQL, MySQL will connect via a Unix socket to the specified socket. For example:

"HOST": "/var/run/mysql"

If you’re using MySQL and this value doesn’t start with a forward slash, then this value is assumed to be the host.

If you’re using PostgreSQL, by default (empty HOST), the connection to the database is done through UNIX domain sockets (‘local’ lines in pg_hba.conf). If your UNIX domain socket is not in the standard location, use the same value of unix_socket_directory from postgresql.conf. If you want to connect through TCP sockets, set HOST to ‘localhost’ or ‘127.0.0.1’ (‘host’ lines in pg_hba.conf). On Windows, you should always define HOST, as UNIX domain sockets are not available.

`NAME`#

Default: '' (Empty string)

The name of the database to use. For SQLite, it’s the full path to the database file. When specifying the path, always use forward slashes, even on Windows (e.g. C:/homes/user/mysite/sqlite3.db).

`CONN_MAX_AGE`#

Default: 0

The lifetime of a database connection, as an integer of seconds. Use 0 to close database connections at the end of each request — GingerDJ’s historical behavior — and None for unlimited persistent database connections.

`CONN_HEALTH_CHECKS`#

Default: False

If set to True, existing persistent database connections will be health checked before they are reused in each request performing database access. If the health check fails, the connection will be reestablished without failing the request when the connection is no longer usable but the database server is ready to accept and serve new connections (e.g. after database server restart closing existing connections).

`OPTIONS`#

Default: {} (Empty dictionary)

Extra parameters to use when connecting to the database. Available parameters vary depending on your database backend.

Some information on available parameters can be found in the Database Backends documentation. For more information, consult your backend module’s own documentation.

`PASSWORD`#

Default: '' (Empty string)

The password to use when connecting to the database. Not used with SQLite.

`PORT`#

Default: '' (Empty string)

The port to use when connecting to the database. An empty string means the default port. Not used with SQLite.

`TIME_ZONE`#

Default: None

A string representing the time zone for this database connection or None. This inner option of the DATABASES setting accepts the same values as the general TIME_ZONE setting.

When USE_TZ is True, reading datetimes from the database returns aware datetimes with the timezone set to this option’s value if not None, or to UTC otherwise.

When USE_TZ is False, it is an error to set this option.

If the database backend doesn’t support time zones (e.g. SQLite, MySQL, Oracle), GingerDJ reads and writes datetimes in local time according to this option if it is set and in UTC if it isn’t.

Changing the connection time zone changes how datetimes are read from and written to the database.
- If GingerDJ manages the database and you don’t have a strong reason to do otherwise, you should leave this option unset. It’s best to store datetimes in UTC because it avoids ambiguous or nonexistent datetimes during daylight saving time changes. Also, receiving datetimes in UTC keeps datetime arithmetic simple — there’s no need to consider potential offset changes over a DST transition.
- If you’re connecting to a third-party database that stores datetimes in a local time rather than UTC, then you must set this option to the appropriate time zone. Likewise, if GingerDJ manages the database but third-party systems connect to the same database and expect to find datetimes in local time, then you must set this option.
If the database backend supports time zones (e.g., PostgreSQL), then the database connection’s time zone is set to this value.

Although setting the TIME_ZONE option is very rarely needed, there are situations where it becomes necessary. Specifically, it’s recommended to match the general TIME_ZONE setting when dealing with raw queries involving date/time functions like PostgreSQL’s date_trunc() or generate_series(), especially when generating time-based series that transition daylight savings.

This value can be changed at any time, the database will handle the conversion of datetimes to the configured time zone.

However, this has a downside: receiving all datetimes in local time makes datetime arithmetic more tricky — you must account for possible offset changes over DST transitions.

Consider converting to local time explicitly with AT TIME ZONE in raw SQL queries instead of setting the TIME_ZONE option.

`DISABLE_SERVER_SIDE_CURSORS`#

Default: False

Set this to True if you want to disable the use of server-side cursors with QuerySet.iterator(). Transaction pooling and server-side cursors describes the use case.

This is a PostgreSQL-specific setting.

`USER`#

Default: '' (Empty string)

The username to use when connecting to the database. Not used with SQLite.

`TEST`#

Default: {} (Empty dictionary)

A dictionary of settings for test databases; for more details about the creation and use of test databases, see The test database.

Here’s an example with a test database configuration:

DATABASES = {
    "default": {
        "ENGINE": "gingerdj.db.backends.postgresql",
        "USER": "mydatabaseuser",
        "NAME": "mydatabase",
        "TEST": {
            "NAME": "mytestdatabase",
        },
    },
}

The following keys in the TEST dictionary are available:

`CHARSET`#

Default: None

The character set encoding used to create the test database. The value of this string is passed directly through to the database, so its format is backend-specific.

Supported by the PostgreSQL (postgresql) and MySQL (mysql) backends.

`COLLATION`#

Default: None

The collation order to use when creating the test database. This value is passed directly to the backend, so its format is backend-specific.

Only supported for the mysql backend (see the MySQL manual for details).

`DEPENDENCIES`#

Default: ['default'], for all databases other than default, which has no dependencies.

The creation-order dependencies of the database. See the documentation on controlling the creation order of test databases for details.

`MIGRATE`#

Default: True

When set to False, migrations won’t run when creating the test database. This is similar to setting None as a value in MIGRATION_MODULES, but for all apps.

`MIRROR`#

Default: None

The alias of the database that this database should mirror during testing. It depends on transactions and therefore must be used within TransactionTestCase instead of TestCase.

This setting exists to allow for testing of primary/replica (referred to as master/slave by some databases) configurations of multiple databases. See the documentation on testing primary/replica configurations for details.

`NAME`#

Default: None

The name of database to use when running the test suite.

If the default value (None) is used with the SQLite database engine, the tests will use a memory resident database. For all other database engines the test database will use the name 'test_' + DATABASE_NAME.

See The test database.

`TEMPLATE`#

This is a PostgreSQL-specific setting.

The name of a template (e.g. 'template0') from which to create the test database.