Custom settings

You can use any of the settings understood by Django and django-ca provides some of its own settings.

How to configure

If you use django-ca as a Django app, set settings normally using your settings.py file (or whatever custom mechanism you have devised).

If you use the full django-ca project (e.g. if you install from source, or use Docker or docker-compose), do not update the settings.py file included with django-ca. Instead, use YAML files that django-ca loads (in alphabetical order) from a preconfigured directory. Please see the respective installation instructions for how to override settings, and see YAML configuration for format instructions.

The django-ca project also lets you override simple string-like settings via environment variables. The environment variable name is the same as the setting but prefixed with DJANGO_CA_. For example to set the CA_DIR setting, pass a DJANGO_CA_CA_DIR environment variable. Environment variables take precedence over the YAML configuration files above.

The django-ca project also recognizes some environment variables to better integrate with other systems. See Global environment variables for more information.

Required Django settings

If you use django-ca as a Django app the only required settings are the settings any Django project requires anyway, most importantly DATABASES, SECRET_KEY, ALLOWED_HOSTS and STATIC_ROOT.

If you install from source, you only have to set the DATABASES and SECRET_KEY settings. The CA_DEFAULT_HOSTNAME also configures the ALLOWED_HOSTS setting if not set otherwise. Please see the section on configuration for more information.

If you use Docker or docker-compose, there isn’t really any standard Django setting you need to configure, as safe defaults are used. A safe value for SECRETS_KEY is generated automatically, ALLOWED_HOSTS is set via CA_DEFAULT_HOSTNAME and the DATABASES setting is automatically populated with environment variables also used by the PostgreSQL/MySQL containers.

Project settings

Project settings are available if you use the full django-ca project (including if you use the Docker container or via docker-compose). Many settings are _not_ prefixed with CA_, because they configure how Django itself works.

As any other setting, they can be set by using environment variables prefixed with DJANGO_CA_ (Example: To set LOG_LEVEL, set the DJANGO_CA_LOG_LEVEL environment variable).

CA_CUSTOM_APPS

Default: []

Warning

This setting is deprecated and will be removed in django-ca==2.5.0. Use settings-extend-installed-apps instead.

The list gets appended to the standard INSTALLED_APPS setting. If you need more control, you can always override that setting instead.

CA_DIR

Default: "files/"

Where the root certificate is stored. The default is a files directory in the same location as your manage.py file.

This setting has no effect if you define a "django-ca" alias in STORAGES (see also: CA_KEY_BACKENDS).

CA_ENABLE_CLICKJACKING_PROTECTION

Default: True

Set to False to disable Clickjacking protection. The setting influences if the XFrameOptionsMiddleware is added to the list of middlewares. This setting is useful if the header is already set by the web server.

CA_URL_PATH

Default: django_ca/

Warning

If you change this settings, OCSP and CRL URLs encoded in existing certificates and intermediate CAs become invalid, so certificate validation using these URLs will fail. Also, ACMEv2 URLs will change, so every ACMEv2 client has to be updated.

If you do change this setting after creating any certificates, you have to either start with a completely fresh set of certificates or make sure that the old URLs continue to work (e.g. by providing your own NGINX configuration).

To URL path to use for ACMEv2, OCSP, CRL and the API, but not the admin interface.

If you use django-ca as app, the effect of this setting is achieved by the URL path given in your root URL conf.

ENABLE_ADMIN

Default: True

Set to False to disable the default Django admin interface. The interface is enabled by default.

EXTEND_INSTALLED_APPS

Default: []

Append Django applications to INSTALLED_APPS.

This setting is extended if given in multiple configuration sources, see EXTEND_* settings for more information.

If this setting is an environment variable, it must be a JSON-encoded list:

["myapp", "otherapp.apps.OtherAppConfig"]

EXTEND_URL_PATTERNS

Default: []

Append URL patterns to the default URL configuration. This allows you to add custom endpoints to your project.

This setting is extended if given in multiple configuration sources, see EXTEND_* settings for more information.

The syntax is very similar to normal URL configuration. For example:

in Python

EXTEND_URL_PATTERNS = [
    # Add a simple view, equivalent to:
    #   path("/path", yourapp.views.YourView.as_view())
    {
        "route": "/path",
        "view": {
            # Can be a function or class-based view:
            "view": "yourapp.views.YourView",
            # Optional: Additional arguments for django.urls.path()
            # "name": "simple-view"
            # "kwargs": {
            #     "foo": "bar",
            # }
        },
    },
    # Add an URL with re_path(),equivalent to:
    #   re_path("^path/(?P<username>\\w+)/$", yourapp.views.YourView.as_view())
    {
        "func": "re_path",
        "route": r"^path/(?P<username>\w+)/$",
        "view": {
            # Can be a function or class-based view:
            "view": "yourapp.views.YourView",
            # Optional: Additional arguments passed to as_view():
            # "initkwargs": {
            #   "foo": "bar",
            # }
        },
        # Optional: Additional arguments for django.urls.re_path()
        # "name": "re-simple-view",
        # "kwargs": {
        #     "foo": "bar",
        # }
    },
    # Add a path via django.urls.include(), equivalent to:
    #   path("/included-path/", include("yourapp.urls"))
    {
        "route": "/included-path/",
        "view": {
            "module": "yourapp.urls",
            # Optional: override the namespace
            # "namespace": "yourapp",
        },
    },
]

with YAML

EXTEND_URL_PATTERNS:
  # Add a simple view, equivalent to:
  #   path("/path", yourapp.views.YourView.as_view())
  - route: /path
    view:
      # Can be a function or class-based view:
      view: yourapp.views.YourView
    # Optional: Additional arguments for django.urls.path()
    #name: simple-view
    #kwargs:
    #  foo: bar

  # Add an URL with re_path(),equivalent to:
  #   re_path("^path/(?P<username>\\w+)/$", yourapp.views.YourView.as_view())
  - type: re_path
    route: "^path/(?P<username>\\w+)/$"
    view:
      # Can be a function or class-based view:
      view: yourapp.views.YourView
      # Optional: Additional arguments passed to as_view():
      #initkwargs:
      #  foo: bar

    # Optional: Additional arguments for django.urls.re_path()
    #name: re-simple-view
    #kwargs:
    #  foo: bar

  # Add a path via django.urls.include(), equivalent to:
  #   include("/included-path/", "yourapp.urls")
  - route: /included-path/
    view:
      module: yourapp.urls
      # Optional: override the namespace
      #namespace: yourapp

If this setting is an environment variable, it must be a JSON-encoded.

LOG_FORMAT

Default: "[%(levelname)-8s %(asctime).19s] %(message)s""

The default log format of log messages. This setting has no effect if you define the LOGGING setting.

LOG_LEVEL

Default: "WARNING"

The log level for all messages from django-ca. This setting has no effect if you define the LOGGING setting.

LIBRARY_LOG_LEVEL

Default: "WARNING"

The log level for all messages _except_ from django-ca. This setting has no effect if you define the LOGGING setting.

SECRET_KEY_FILE

Default: "/var/lib/django-ca/secret_key"

A path to a file that stores Django’s SECRET_KEY. The setting is only used if no SECRET_KEY is defined.

If you use Docker/docker-compose, the file is automatically generated with a random value on first startup. You only have to use this setting if you want to specify a custom value for some reason. If you use docker-compose, you should make sure that frontend and backend container have access to the same file.

Global environment variables

If you use the full django-ca project (e.g. if you install from source or use Docker or docker-compose), you can also make use of some environment variables set by other systems.

Configuration directory

The django-ca project reads custom settings from YAML files in a directory.

All installation options already include a good default for this environment variable and examples in the quickstart guides assume it is not modified. It is documented here for completeness.

DJANGO_CA_SETTINGS

The directory where to load YAML settings files. All files in the directory that have a .yaml suffix will be read in alphabetical order.

Multiple directories can be separated by a colon (":"). In this case, django-ca will first read all directories from the first directory, then from the second one, and so on.

The setting can also point to a single file, assumed to be a YAML file.

If not set, the value of the CONFIGURATION_DIRECTORY environment variable (see SystemD) is used as a fallback.

Startup (Docker only)

The startup scripts in the Docker container read environment variables that influence the startup behavior.

By default, all manage.py commands are run on startup, but the Compose setup disables them on some containers to optimize startup times and ensure that they are only run once.

DJANGO_CA_STARTUP_CACHE_CRLS

Set to 0 if you don’t want to run manage.py cache_crls on startup.

DJANGO_CA_STARTUP_CHECK

Set to 0 if you don’t want to run manage.py check (see Djangos system check framework on startup. This will save a second or two in container startup time.

DJANGO_CA_STARTUP_COLLECTSTATIC

Set to 0 if you don’t want to run manage.py collectstatic on startup.

DJANGO_CA_STARTUP_MIGRATE

Set to 0 if you don’t want to run manage.py migrate on startup.

DJANGO_CA_STARTUP_REGENERATE_OCSP_KEYS

Set to 0 if you don’t want to run manage.py regenerate_ocsp_keys on startup.

DJANGO_CA_STARTUP_WAIT_FOR_CONNECTIONS

A space-separated string in the form of hostname:port, for example db.example.com:5432. If set, the startup script will make a TCP connection attempt until the connection succeeds. This can be useful to ensure that the main application does not start unless other systems are running.

This is useful if the startup script is configured to run other manage.py commands that require access to the database. Note that the Compose setup already asserts that via healthcheck commands.

DJANGO_CA_STARTUP_WAIT_FOR_SECRET_KEY_FILE

Set to 1 to wait for the secret key file to be created elsewhere. This is used in the Compose setup to ensure that one container generates and writes a secret key to a file and the other containers then read that file.

Databases

Both the PostgreSQL and MySQL Docker containers get their database name and access credentials from environment variables and django-ca also recognizes these variables.

This is especially powerful when using docker-compose, where it is sufficient to set the POSTGRES_PASSWORD environment variable to configure the database, all other options use default values that just work.

But any other setup can also make use of this feature. For example, with plain Docker, you could just configure PostgreSQL:

localsettings.yaml

DATABASES:
  default:
    ENGINE: django.db.backends.postgresql

… and then start your docker containers with (not a full example here):

$ docker run -e POSTGRES_PASSWORD=... postgres
$ docker run -e POSTGRES_PASSWORD=... mathiasertl/django-ca

POSTGRES_DB, POSTGRES_DB_FILE, POSTGRES_USER, POSTGRES_USER_FILE, POSTGRES_PASSWORD, POSTGRES_PASSWORD_FILE: Access details to a PostgreSQL database. See the Docker image documentation for more information.
MYSQL_DATABASE, MYSQL_DATABASE_FILE, MYSQL_USER, MYSQL_USER_FILE, MYSQL_PASSWORD, MYSQL_PASSWORD_FILE: Access details to a MySQL database. See the Docker image documentation for more information.
MARIADB_DATABASE, MARIADB_DATABASE_FILE, MARIADB_USER, MARIADB_USER_FILE, MARIADB_PASSWORD, MARIADB_PASSWORD_FILE: Access details to a MariaDB database. See the Docker image documentation for more information.

NGINX

The compose.yaml file provided by the project uses environment variables to parameterize the NGINX configuration. Except for NGINX_TEMPLATE, these environment variables are not used by django-ca itself, but only by the NGINX container itself. As usual, you have to set these variables in your .env file, for example:

.env

# NGINX TLS configuration
NGINX_TEMPLATE=tls
NGINX_PRIVATE_KEY=/etc/certs/live/ca.example.com/privkey.pem
NGINX_PUBLIC_KEY=/etc/certs/live/ca.example.com/fullchain.pem

NGINX_HOST

Default: value of DJANGO_CA_CA_DEFAULT_HOSTNAME

The hostname used by the web server. Internally, this is used in the server_name directive. The default is to use the value of DJANGO_CA_CA_DEFAULT_HOSTNAME, so you usually do not have to configure this variable.

NGINX_HTTPS_PORT

Default: 443

The HTTPS port to use for HTTPS connections. This is only used if you use NGINX_TEMPLATE=tls.

NGINX_PORT

Default: 80

The HTTP port to use for HTTP connections.

NGINX_PRIVATE_KEY

Path to the TLS private key. This is only used if you use NGINX_TEMPLATE=tls.

NGINX_PUBLIC_KEY

Path to the TLS public key. This is only used if you use NGINX_TEMPLATE=tls.

NGINX_TEMPLATE

Default: default

The configuration template to use. There are currently only two templates provided by django-ca:

default: The “simple” default configuration, providing all access via plain HTTP.
tls: A configuration that includes TLS configuration. It requires that you also set NGINX_PRIVATE_KEY and NGINX_PUBLIC_KEY.

SystemD

The django-ca project also recognizes some environment variables set by SystemD.

The SystemD services included in our quickstart guide already set this variable and further examples assume that you did not modify it. It is documented here for completeness.

CONFIGURATION_DIRECTORY: If set, django-ca will load YAML configuration files from this directory. The variable is set by the ConfigurationDirectory= directive.

YAML configuration

The Django project you use if you install from source, use Docker or docker-compose loads YAML files from a directory. This enables you to configure django-ca with a normal configuration file format without having to know Python.

Warning: unquoted strings

A file will fail to load if an unquoted string starts with a character that is also used in the YAML syntax, for example with a * or a [. This is invalid YAML:

# THIS WILL NOT WORK:
SECRET_KEY: [random-string-that-happens-to-start-with-a-bracket

Strings must also be quoted if they contain only digits (or resemble a different YAML data type), as they would otherwise be loaded as the respective data type:

# WRONG: serial that happens to have only digits would be loaded as integer
CA_DEFAULT_CA: 12345

In both cases, the solution is to quote the string:

SECRET_KEY: "[random-string-that-happens-to-start-with-a-bracket"
CA_DEFAULT_CA: "12345"

Examples

Basic settings are straight forward:

# Use this hostname in CRL and OCSP URLs:
CA_DEFAULT_HOSTNAME: ca.example.com

# Certificates should expire after a year by default
CA_DEFAULT_EXPIRES: 365

Nested mappings such as the DATABASES are of course also possible:

DATABASES:
  default:
    ENGINE: django.db.backends.postgresql
    HOST: database.int.example.com
    PORT: 5444

Settings that are tuples like CA_DEFAULT_SUBJECT have to be defined as lists:

CA_DEFAULT_SUBJECT:
  - ["O", "DefaultOrg"]
  - ["OU", "Default OrgUnit"]
  - ["OU", "Default OrgUnit 2"]

The CA_PROFILES setting can also be set using YAML. Here is a verbose example:

CA_PROFILES:
  # Remove the "enduser" profile included in the default configuration
  enduser: null

  # Add a new profile
  new_profile:
    description: The description for the new profile
    expires: 1095

    # Certificates using this profile should have a custom subject
    subject:
      - ["C", "AT"]
      - ["O", "MyOrg"]
      - ["OU", "My OrgUnit"]
      - ["emailAddress", "ca@example.com"]

    # Set default extensions for this profile
    extensions:
      # Add the Certificate Policy extension
      certificate_policies:
        value:
          - policy_identifier: "2.5.29.32.0"
            policy_qualifiers: ["A certificate policy"]

      # The Key Usage extension will be critical by default
      key_usage:
        value:
          - digitalSignature
          - keyAgreement
          - keyEncipherment

      # Extended Key Usage is not critical by default
      extended_key_usage:
        value:
          - clientAuth
          - serverAuth

      # Add a critical Issuer Alternative Name extension (is non-critical by default)
      issuer_alternative_name:
        critical: true
        value:
          -  URI:https://ca.example.com

`EXTEND_*` settings

Settings that are prefixed with EXTEND_ are used to extend a different setting. If you use the full django-ca project (e.g. if you install from source, or use Docker or docker-compose) and have multiple configuration sources, the setting will be extended by all instances in this setting.

For example, if you have:

conf/10-enable-first-app.yaml

EXTEND_INSTALLED_APPS:
   - first_app

and:

conf/20-enable-second-app.yaml

EXTEND_INSTALLED_APPS:
   - second_app

… then both first_app and second_app will be added to INSTALLED_APPS.

Custom settings

How to configure

Required Django settings

django-ca settings

ACMEv2 settings

Project settings

Global environment variables

Configuration directory

Startup (Docker only)

Databases

NGINX

SystemD

YAML configuration

Warning: unquoted strings

Examples

`EXTEND_*` settings

Custom settings

How to configure

Required Django settings

django-ca settings

ACMEv2 settings

Project settings

Global environment variables

Configuration directory

Startup (Docker only)

Databases

NGINX

SystemD

YAML configuration

Warning: unquoted strings

Examples

EXTEND_* settings

`EXTEND_*` settings