Configuration Options

The functionality and features of CKAN can be modified using many different configuration options. These are generally set in the CKAN configuration file, but some of them can also be set via Environment variables or at runtime.

Note

Looking for the available configuration options? Jump to CKAN configuration file.

Environment variables

Some of the CKAN configuration options can be defined as Environment variables on the server operating system.

These are generally low-level critical settings needed when setting up the application, like the database connection, the Solr server URL, etc. Sometimes it can be useful to define them as environment variables to automate and orchestrate deployments without having to first modify the CKAN configuration file.

These options are only read at startup time to update the config object used by CKAN, but they won’t be accessed any more during the lifetime of the application.

CKAN environment variable names match the options in the configuration file, but they are always uppercase and prefixed with CKAN_ (this prefix is added even if the corresponding option in the ini file does not have it), and replacing dots with underscores.

This is the list of currently supported environment variables, please refer to the entries in the CKAN configuration file section below for more details about each one:

CONFIG_FROM_ENV_VARS: dict[str, str] = {
    'sqlalchemy.url': 'CKAN_SQLALCHEMY_URL',
    'ckan.datastore.write_url': 'CKAN_DATASTORE_WRITE_URL',
    'ckan.datastore.read_url': 'CKAN_DATASTORE_READ_URL',
    'ckan.redis.url': 'CKAN_REDIS_URL',
    'solr_url': 'CKAN_SOLR_URL',
    'solr_user': 'CKAN_SOLR_USER',
    'solr_password': 'CKAN_SOLR_PASSWORD',
    'ckan.site_id': 'CKAN_SITE_ID',
    'ckan.site_url': 'CKAN_SITE_URL',
    'ckan.storage_path': 'CKAN_STORAGE_PATH',
    'ckan.datapusher.url': 'CKAN_DATAPUSHER_URL',
    'smtp.server': 'CKAN_SMTP_SERVER',
    'smtp.starttls': 'CKAN_SMTP_STARTTLS',
    'smtp.user': 'CKAN_SMTP_USER',
    'smtp.password': 'CKAN_SMTP_PASSWORD',
    'smtp.mail_from': 'CKAN_SMTP_MAIL_FROM',
    'ckan.max_resource_size': 'CKAN_MAX_UPLOAD_SIZE_MB'
}

Updating configuration options during runtime

CKAN configuration options are generally defined before starting the web application (either in the CKAN configuration file or via Environment variables).

A limited number of configuration options can also be edited during runtime. This can be done on the administration interface or using the config_option_update() API action. Only sysadmins can edit these runtime-editable configuration options. Changes made to these configuration options will be stored in the database and persisted when the server is restarted.

Extensions can add (or remove) configuration options to the ones that can be edited at runtime. For more details on how to do this check Making configuration options runtime-editable.

Config declaration

Tracking down all the possible config options in your CKAN site can be a challenging task. CKAN itself and its extensions change over time, deprecating features and providing new ones, which means that some new config options may be introduced, while other options no longer have any effect. In order to keep track of all valid config options, CKAN uses config declarations.

CKAN itself declares all the config options that are used throught the code base (You can see the core config declarations in the ckan/config/config_declaration.yaml file). This allows to validate the current configuration against the declaration, or check which config options in the CKAN config file are not declared (and might have no effect).

Declaring config options

Note

Starting from CKAN 2.11, CKAN will log a warning every time a non-declared configuration option is accessed. To prevent this, declare the configuration options offered by your extension using the methods below

Using a text file (JSON, YAML or TOML)

The recommended way of declaring config options is using the config_declarations blanket. It allows you to write less code and define your config options using JSON, YAML, or TOML (if the toml package is installed inside your virtual environment). That is how CKAN declares config options for all its built-in plugins, like datastore or datatables_view.

To use it, decorate the plugin with the config_declarations blanket:

import ckan.plugins as p
import ckan.plugins.toolkit as tk

@tk.blanket.config_declarations
class MyExt(p.SingletonPlugin):
    pass

Next, create a file config_declaration.yaml at the root directory of your extension: ckanext/my_ext/config_declaration.yaml. You can use the .json or .toml extension instead of .yaml.

Here is an example of the config declaration file. All the comments are added only for explanation and you don’t need them in the real file:

# schema version of the config declaration. At the moment, the only valid value is `1`
version: 1

# an array of configuration blocks. Each block has an "annotation", that
# describes the block, and the list of options. These groups help to separate
# config options visually, but they have no extra meaning.
groups:

# short text that describes the group. It can be shown in the config file
# as following:
#   ## MyExt settings ##################
#   some.option = some.value
#   another.option = another.value
- annotation: MyExt settings

  # an array of actual declarations
  options:

    # The only required item in the declaration is `key`. `key` defines the
    # name of the config option
    - key: my_ext.flag.do_something

      # default value, used when the option is missing from the config file.
      default: false

      # import path of the function that must be called in order to get the
      # default value. This can be used when the default value can be obtained from
      # an environment variable, database or any other external source.
      # IMPORTANT: use either `default` or `default_callable`, not both at the same time
      default_callable: ckanext.my_ext.utils:function_that_returns_default

      # Example of value that can be used for given option. If the config
      # option is missing from the config file, `placeholder` IS IGNORED. It
      # has only demonstration purpose. Good uses of `placeholder` are:
      # examples of secrets, examples of DB connection string.
      # IMPORTANT: do not use `default` and `placeholder` at the same
      # time. `placeholder` should be used INSTEAD OF the `default`
      # whenever you think it has a sense.
      placeholder: false

      # import path of the function that must be called in order to get the
      # placeholder value.  Basically, same as `default_callable`, but it
      # produces the value of `placeholder`.
      # IMPORTANT: use either `placeholder` or `placeholder_callable`, not both at the same time
      placeholder_callable: ckanext.my_ext.utils:function_that_returns_placeholder

      # A dictionary with keyword-arguments that will be passed to
      # `default_callable` or `placeholder_callable`.  As mentioned above,
      # only one of these options may be used at the same time, so
      # `callable_args` can be used by any of these options without a conflict.
      callable_args:
        arg_1: 20
        arg_2: "hello"

      # an alternative example of a valid value for option. Used only in
      # CKAN documentation, thus has no value for extensions.
      example: some-valid-value

      # an explanation of the effect that option has. Don't hesistate to
      # put as much details here as possible
      description: |
          Nullam eu ante vel est convallis dignissim.  Fusce suscipit, wisi
          nec facilisis facilisis, est dui fermentum leo, quis tempor
          ligula erat quis odio.  Nunc porta vulputate tellus.  Nunc rutrum
          turpis sed pede.  Sed bibendum.  Aliquam posuere.  Nunc aliquet,
          augue nec adipiscing interdum, lacus tellus malesuada massa, quis
          varius mi purus non odio.  Pellentesque condimentum, magna ut
          suscipit hendrerit, ipsum augue ornare nulla, non luctus diam
          neque sit amet urna.  Curabitur vulputate vestibulum lorem.
          Fusce sagittis, libero non molestie mollis, magna orci ultrices
          dolor, at vulputate neque nulla lacinia eros.  Sed id ligula quis
          est convallis tempor.  Curabitur lacinia pulvinar nibh.  Nam a
          sapien.

      # a space-separated list of validators, applied to the value of option.
      validators: not_missing boolean_validator

      # shortcut for the most common option types. It adds type validators to the option.
      # If both, `type` and `validators` are set, validators from `type` are added first,
      # then validators from `validators` are appended.
      # Valid types are: bool, int, list, dynamic (see below for more information on dynamic
      # options)
      type: bool

      # boolean flag that marks config option as experimental. Such options are hidden from
      # examples of configuration or any other auto-generated output. But they are declared,
      # thus can be validated and do not produce undeclared-warning. Use it for options that
      # are not stable and may be removed from your extension before the public release
      experimental: true

      # boolean flag that marks config option as ignored. Can be used for options that are set
      # programmatically. This flag means that there is no sense in setting this option, because
      # it will be overriden or won't be used at all.
      ignored: true

      # boolean flag that marks config option as hidden. Used for options that should not be set
      # inside config file or anyhow used by others. Often this flag is used for options
      # that are added by Flask core or its extensions.
      internal: true

      # boolean flag that marks config option as required. Doesn't have a special effect for now,
      # but may prevent application from startup in future, so use it only on options that
      # are essential for your plugin and that have no sensible default value.
      required: true

      # boolean flag that marks config option as editable. Doesn't have a special effect for now.
      # It's recommended to enable this flag for options that are editable via AdminUI.
      editable: true

      # boolean flag that marks option as commented. Such options are added
      # as comments to the config file generated from template.
      commented: true

      # Deprecated name of the option. Can be used for options that were renamed.
      # When `key` is missing from config and `legacy_key` is available, the value of
      # `legacy_key` is used, printing a deprecation warning in the logs.
      legacy_key: my_ext.legacy.flag.do_something

The IConfigDeclaration interface

The IConfigDeclaration interface is available to plugins that want more control on how their own config options are declared.

New config options can only be declared inside the declare_config_options() method. This method accepts two arguments: a Declaration object that contains all the declarations, and a Key helper, which allows to declare more unusual config options.

A very basic config option may be declared in this way:

declaration.declare("ckanext.my_ext.option")

which just means that extension my_ext makes use of a config option named ckanext.my_ext.option. If we want to define the default value for this option we can write:

declaration.declare("ckanext.my_ext.option", True)

The second parameter to declare() specifies the default value of the declared option if it is not provided in the configuration file. If a default value is not specified, it’s implicitly set to None.

You can assign validators to a declared config option:

option = declaration.declare("ckanext.my_ext.option", True)
option.set_validators("not_missing boolean_validator")

set_validators accepts a string with the names of validators that must be applied to the config option. These validators need to registered in CKAN core or in your own extension using the IValidators interface.

Note

Declared default values are also passed to validators. In addition, different validators can be applied to the same option multiple times. This means that validators must be idempotent and that the default value itself must be valid for the given set of validators.

If you need to declare a lot of options, you can declare all of them at once loading a dict:

declaration.load_dict(DICT_WITH_DECLARATIONS)

This allows to keep the configuration declaration in a separate file to make it easier to maintain if your plugin supports several config options.

Note

declaration.load_dict() takes only python dictionary as argument. If you store the declaration in an external file like a JSON, YAML file, you have to parse it into a Python dictionary yourself or use corresponding blanket. Read the following section for additional information.

Dynamic config options

There is a special option type, dynamic. This option type is used for a set of options that have common name-pattern. Because dynamic type defines multiple options, it has no default, validators and serves mostly documentation purposes. Let’s use CKAN’s sqlalchemy.* options as example. Every option whose name follows the pattern sqlalchemy.SOMETHING is passed to the SQLAlchemy engine created by CKAN. CKAN doesn’t actually know which options are valid and it’s up to you to provide valid values. Basically, we have a set of options with prefix sqlalchemy.. If use these options without declararing, it will trigger warnings about using undeclared options, which are harmless but can be annoying. Declaring them helps to make explicit which configuration options are actually being used. In order to declare such set of options, put some label surrounded with angle brackets instead of the dynamic part of option’s name. In our case it can be sqlalchemy.<OPTION> or sqlalchemy.<anything>. Any word can be used as label, the only important part here are angle brackets:

- key: sqlalchemy.<OPTION>
  type: dynamic
  description: |
    Example::

     sqlalchemy.pool_pre_ping=True
     sqlalchemy.pool_size=10
     sqlalchemy.max_overflow=20

    Custom sqlalchemy config parameters used to establish the main
    database connection.

Use this feature sparsely, only when you really want to declare literally ANY value following the pattern. If you have finite set of possible options, consider declaring all of them, because it allows you to provide validators, defaults, and prevents you from accidental shadowing unrelated options.

Accessing config options

Using validators ensures that config values are normalized. Up until now you have probably seen code like this one:

is_enabled = toolkit.asbool(toolkit.config.get("ckanext.my_ext.enable", False))

Declaring this configuration option and assigning validators (convert_int, boolean_validators) and a default value means that we can use the config.get(key) instead of the expression above:

is_enabled = toolkit.config.get("ckanext.my_ext.enable")

This will ensure that:

1. If the value is not explicitly defined in the configuration file, the default one will be picked

2. This value is passed to the validators, and a valid value is returned

Note

An attempt to use config.get() with an undeclared config option will print a warning to the logs and return the option value or None as default.

Command line interface

The current configuration can be validated using the config declaration CLI:

ckan config validate

To get an example of the configuration for a given plugin, run ckan config declaration <PLUGIN>, eg:

ckan config declaration datastore

## Datastore settings ##########################################################
ckan.datastore.write_url = postgresql://ckan_default:pass@localhost/datastore_default
ckan.datastore.read_url = postgresql://datastore_default:pass@localhost/datastore_default
ckan.datastore.sqlsearch.enabled = false
ckan.datastore.search.rows_default = 100
ckan.datastore.search.rows_max = 32000
# ckan.datastore.sqlalchemy.<OPTION> =

## PostgreSQL' full-text search parameters #####################################
ckan.datastore.default_fts_lang = english
ckan.datastore.default_fts_index_method = gist

To get an example of the declaration code itself in order to use it as a starting point in your own plugin, you can run ckan config describe <PLUGIN>, eg:

ckan config describe datapusher

# Output:
declaration.annotate('Datapusher settings')
declaration.declare(key.ckan.datapusher.formats, ...)
declaration.declare(key.ckan.datapusher.url)
declaration.declare(key.ckan.datapusher.callback_url_base)
declaration.declare(key.ckan.datapusher.assume_task_stale_after, 3600).set_validators('convert_int')

You can output the config declaration in different formats, which is useful if you want to keep them separately:

ckan config describe datapusher --format=dict # python dict
ckan config describe datapusher --format=json # JSON file
ckan config describe datapusher --format=yaml # YAML file
ckan config describe datapusher --format=toml # TOML file

CKAN configuration file

From CKAN 2.9, by default, the configuration file is located at /etc/ckan/default/ckan.ini. Previous releases the configuration file(s) were: /etc/ckan/default/development.ini or /etc/ckan/default/production.ini. This section documents all of the config file settings, for reference.

Note

After editing your config file, you need to restart your webserver for the changes to take effect.

Note

Unless otherwise noted, all configuration options should be set inside the [app:main] section of the config file (i.e. after the [app:main] line):

[DEFAULT]

...

[server:main]
use = egg:Paste#http
host = 0.0.0.0
port = 5000

# This setting will not work, because it's outside of [app:main].
ckan.site_logo = /images/masaq.png

[app:main]
# This setting will work.
ckan.plugins = stats text_view datatables_view

If the same option is set more than once in your config file, exeption will be raised and CKAN application will not start

Default settings

debug

Example:

debug = true

Default value: False

This enables the Flask-DebugToolbar in the web interface, makes Webassets serve unminified JS and CSS files, and enables CKAN templates’ debugging features.

You will need to ensure the Flask-DebugToolbar python package is installed, by activating your ckan virtual environment and then running:

pip install -r /usr/lib/ckan/default/src/ckan/dev-requirements.txt

If you are running CKAN on Apache, you must change the WSGI configuration to run a single process of CKAN. Otherwise the execution will fail with: AssertionError: The EvalException middleware is not usable in a multi-process environment. Eg. change:

WSGIDaemonProcess ckan_default display-name=ckan_default processes=2 threads=15
to
WSGIDaemonProcess ckan_default display-name=ckan_default threads=15

Warning

This option should be set to False for a public site. With debug mode enabled, a visitor to your site could execute malicious commands.

General settings

SECRET_KEY

Default value: none

This is the secret token that is used by security related tasks by CKAN and its extensions. ckan generate config generates a unique value for this each time it generates a config file. Alternatively you can generate one with the following command:

python -c "import secrets; print(secrets.token_urlsafe(20))"

When used in a cluster environment, the value must be the same on every machine.

ckan.legacy_route_mappings

Example:

ckan.legacy_route_mappings = {"home": "home.index", "about": "home.about", "search": "dataset.search"}

Default value: {}

This can be used when using an extension that is still using old (Pylons-based) route names to maintain compatibility.

Warning

This configuration will be removed when the migration to Flask is completed. Please update the extension code to use the new Flask-based route names.

config.mode

Example:

config.mode = strict

Default value: strict

Warning

This configuration option has no effect starting from CKAN 2.11. The default behaviour going forward is the old strict mode, where CKAN will not start unless all config options are valid according to the validators defined in the configuration declaration. For every invalid config option, an error will be printed to the output stream.

Development settings

ckan.devserver.host

Example:

ckan.devserver.host = 0.0.0.0

Default value: localhost

Host name to use when running the development server.

ckan.devserver.port

Example:

ckan.devserver.port = 5005

Default value: 5000

Port to use when running the development server.

ckan.devserver.threaded

Example:

ckan.devserver.threaded = true

Default value: False

Controls whether the development server should handle each request in a separate thread.

ckan.devserver.multiprocess

Example:

ckan.devserver.multiprocess = 8

Default value: 1

If greater than 1 then the development server will handle each request in a new process, up to this maximum number of concurrent processes.

ckan.devserver.watch_patterns

Example:

ckan.devserver.watch_patterns = mytheme/**/*.yaml mytheme/**/*.json

Default value: none

A list of files the reloader should watch to restart the development server, in addition to the Python modules (for example configuration files)

ckan.devserver.ssl_cert

Example:

ckan.devserver.ssl_cert = path/to/host.cert

Default value: none

Path to a certificate file that will be used to enable SSL (ie to serve the local development server on https://localhost:5000). You can generate a self-signed certificate and key (see ckan.devserver.ssl_key) running the following commands:

openssl genrsa 2048 > host.key
chmod 400 host.key
openssl req -new -x509 -nodes -sha256 -days 3650 -key host.key > host.cert

After that you can run CKAN locally with SSL using this command:

ckan -c /path/to/ckan.ini run --ssl-cert=/path/to/host.cert --ssl-key=/path/to/host.key

Alternatively, setting this option to adhoc will automatically generate a new certificate file (on each server reload, which means that you’ll get a browser warning about the certificate on each reload).

ckan.devserver.ssl_key

Example:

ckan.devserver.ssl_key = path/to/host.key

Default value: none

Path to a certificate file that will be used to enable SSL (ie to serve the local development server on https://localhost:5000). See ckan.devserver.ssl_cert for more details. This option also supports the adhoc value, with the same caveat.

Session settings

ckan.user.last_active_interval

Default value: 600

The number of seconds between requests to record the last time a user was active on the site.

beaker.session.key

Default value: ckan

Name of the cookie key used to save the session under.

beaker.session.secret

Default value: none

This is the secret token that the beaker library uses to hash the cookie sent to the client. ckan generate config generates a unique value for this each time it generates a config file. When used in a cluster environment, the value must be the same on every machine. If not provided, the value of SECRET_KEY will be used.

beaker.session.auto

Default value: False

When set to True, the session will save itself anytime it is accessed during a request, negating the need to issue the save() method.

beaker.session.cookie_expires

Default value: False

Determines when the cookie used to track the client-side of the session will expire. When set to a boolean value, it will either expire at the end of the browsers session, or never expire. Setting to a datetime forces a hard ending time for the session (generally used for setting a session to a far off date). Setting to an integer will result in the cookie being set to expire in that many seconds. I.e. a value of 300 will result in the cookie being set to expire in 300 seconds. Defaults to never expiring.

beaker.session.cookie_domain

Default value: none

What domain the cookie should be set to. When using sub-domains, this should be set to the main domain the cookie should be valid for. For example, if a cookie should be valid under www.nowhere.com and files.nowhere.com then it should be set to .nowhere.com. Defaults to the current domain in its entirety.

beaker.session.save_accessed_time

Default value: True

Whether beaker should save the session’s access time (true) or only modification time (false).

beaker.session.secure

Default value: False

Whether or not the session cookie should be marked as secure. When marked as secure, browsers are instructed to not send the cookie over anything other than an SSL connection.

beaker.session.timeout

Default value: none

Seconds until the session is considered invalid, after which it will be ignored and invalidated. This number is based on the time since the session was last accessed, not from when the session was created. Defaults to never expiring. Requires that save_accessed_time be true.

beaker.session.type

Default value: cookie

The type of session to use. The default is cookie, which uses a cookie to store the session id. Other options include file, which stores the session id in a file, and dbm, which stores the session id in a dbm file. The dbm option is not recommended as it is not thread-safe.

beaker.session.validate_key

Default value: none

This is the secret token that is used to sign the local encrypted session. ckan generate config generates a unique value for this each time it generates a config file. When used in a cluster environment, the value must be the same on every machine. If not provided, the value of SECRET_KEY will be used.

beaker.session.httponly

Default value: True

Whether or not the session cookie should be marked as http only. When marked as http only, browsers are instructed to not allow javascript access to the cookie.

beaker.session.samesite

Default value: Lax

Whether or not the session cookie should be marked as SameSite. When marked as SameSite, browsers are instructed to not send the cookie with cross-site requests. The value can be “Strict”, “Lax” or “None”.

Database settings

sqlalchemy.url

Example:

sqlalchemy.url = postgres://tester:pass@localhost/ckantest3

Default value: none

This defines the database that CKAN is to use. The format is:

sqlalchemy.url = postgres://USERNAME:PASSWORD@HOST/DBNAME

sqlalchemy.<OPTION>

Default value: none

Example:

sqlalchemy.pool_pre_ping=True
sqlalchemy.pool_size=10
sqlalchemy.max_overflow=20

Custom sqlalchemy config parameters used to establish the main database connection.

To get the list of all the available properties check the SQLAlchemy documentation

Site Settings

ckan.site_url

Example:

ckan.site_url = http://scotdata.ckan.net

Default value: none

Set this to the URL of your CKAN site. Many CKAN features that need an absolute URL to your site use this setting.

This setting should only contain the protocol (e.g. http://), host (e.g. www.example.com) and (optionally) the port (e.g. :8080). In particular, if you have mounted CKAN at a path other than / then the mount point must not be included in ckan.site_url. Instead, you need to set ckan.root_path.

Important

It is mandatory to complete this setting

Warning

This setting should not have a trailing / on the end.

apitoken_header_name

Example:

apitoken_header_name = X-CKAN-API-TOKEN

Default value: Authorization

This allows to customize the name of the HTTP header used to provide the CKAN API token. This is useful in some scenarios where using the default Authorization one causes problems.

ckan.cache_expires

Example:

ckan.cache_expires = 2592000

Default value: 0

This sets Cache-Control header’s max-age value.

ckan.cache_enabled

Example:

ckan.cache_enabled = true

Default value: False

This enables cache control headers on all requests. If the user is not logged in and there is no session data a Cache-Control: public header will be added. For all other requests the Cache-control: private header will be added.

ckan.mimetype_guess

Example:

ckan.mimetype_guess = file_contents

Default value: file_ext

There are three options for guessing the mimetype of uploaded or linked resources: file_ext, file_contents, None.

file_ext will guess the mimetype by the url first, then the file extension.

file_contents will guess the mimetype by the file itself, this tends to be inaccurate.

None will not store the mimetype for the resource.

ckan.static_max_age

Example:

ckan.static_max_age = 2592000

Default value: 3600

Controls CKAN static files’ cache max age, if we’re serving and caching them.

ckan.valid_url_schemes

Example:

ckan.valid_url_schemes = http https ftp sftp

Default value: http https ftp

Controls what uri schemes are rendered as links.

ckan.requests.timeout

Example:

ckan.requests.timeout = 10

Default value: 5

Defines how long (in seconds) requests calls should last before they will timeout.

ckan.hide_version

Example:

ckan.hide_version = True

Default value: False

If set to True, CKAN will not publicly expose its version number.

Authorization Settings

ckan.auth.anon_create_dataset

Example:

ckan.auth.anon_create_dataset = false

Default value: False

Allow users to create datasets without registering and logging in.

ckan.auth.create_unowned_dataset

Example:

ckan.auth.create_unowned_dataset = false

Default value: False

Allow the creation of datasets not owned by any organization.

ckan.auth.create_dataset_if_not_in_organization

Example:

ckan.auth.create_dataset_if_not_in_organization = false

Default value: True

Allow users who are not members of any organization to create datasets, default: true. create_unowned_dataset must also be True, otherwise setting create_dataset_if_not_in_organization to True is meaningless.

ckan.auth.user_create_groups

Example:

ckan.auth.user_create_groups = true

Default value: True

Allow users to create groups.

ckan.auth.user_create_organizations

Example:

ckan.auth.user_create_organizations = false

Default value: True

Allow users to create organizations.

ckan.auth.user_delete_groups

Example:

ckan.auth.user_delete_groups = false

Default value: True

Allow users to delete groups.

ckan.auth.user_delete_organizations

Example:

ckan.auth.user_delete_organizations = false

Default value: True

Allow users to delete organizations.

ckan.auth.create_user_via_api

Example:

ckan.auth.create_user_via_api = false

Default value: False

Allow new user accounts to be created via the API by anyone. When False only sysadmins are authorised.

ckan.auth.create_user_via_web

Example:

ckan.auth.create_user_via_web = true

Default value: False

Allow new user accounts to be created via the web UI. When False (default value), user accounts can only be created by:

• Being invited by an organization admin,

• Being created directly by a sysadmin in the /user/register endpoint, or

• Being created in the CLI using ckan user add

ckan.auth.roles_that_cascade_to_sub_groups

Example:

ckan.auth.roles_that_cascade_to_sub_groups = admin editor

Default value: admin

Makes role permissions apply to all the groups or organizations down the hierarchy from the groups or organizations that the role is applied to. e.g. a particular user has the ‘admin’ role for group ‘Department of Health’. If you set the value of this option to ‘admin’ then the user will automatically have the same admin permissions for the child groups of ‘Department of Health’ such as ‘Cancer Research’ (and its children too and so on).

ckan.auth.public_user_details

Example:

ckan.auth.public_user_details = false

Default value: True

Restricts anonymous access to user information. If is set to False accessing users details when not logged in will raise a Not Authorized exception.

Note

This setting should be used when user registration is disabled (ckan.auth.create_user_via_web = False), otherwise users can just create an account to see other users details.

ckan.auth.public_activity_stream_detail

Example:

ckan.auth.public_activity_stream_detail = true

Default value: False

Restricts access to ‘view this version’ and ‘changes’ in the Activity Stream pages. These links provide users with the full edit history of datasets etc - what they showed in the past and the diffs between versions. If this option is set to False then only admins (e.g. whoever can edit the dataset) can see this detail. If set to True, anyone can see this detail (assuming they have permission to view the dataset etc).

ckan.auth.allow_dataset_collaborators

Example:

ckan.auth.allow_dataset_collaborators = true

Default value: False

Enables or disable collaborators in individual datasets. If True, in addition to the standard organization based permissions, users can be added as collaborators to individual datasets with different roles, regardless of the organization they belong to. For more information, check the documentation on Dataset collaborators.

Warning

If this setting is turned off in a site where there already were collaborators created, you must reindex all datasets to update the permission labels, in order to prevent access to private datasets to the previous collaborators.

ckan.auth.allow_admin_collaborators

Example:

ckan.auth.allow_admin_collaborators = true

Default value: False

Allows dataset collaborators to have the “Admin” role, allowing them to add more collaborators or remove existing ones. By default, collaborators can only be managed by administrators of the organization the dataset belongs to. For more information, check the documentation on Dataset collaborators.

Warning

If this setting is turned off in a site where admin collaborators have been already created, existing collaborators with role “admin” will no longer be able to add or remove collaborators, but they will still be able to edit and access the datasets that they are assigned to.

ckan.auth.allow_collaborators_to_change_owner_org

Example:

ckan.auth.allow_collaborators_to_change_owner_org = true

Default value: False

Allows dataset collaborators to change the owner organization of the datasets they are collaborators on. Defaults to False, meaning that collaborators with role admin or editor can edit the dataset metadata but not the organization field.

ckan.auth.create_default_api_keys

Example:

ckan.auth.create_default_api_keys = true

Default value: False

Determines if an API key should be automatically created for every user when creating a user account. If set to False (the default value), users can manually create an API token from their profile instead. See Authentication and API tokens: for more details.

ckan.auth.login_view

Default value: user.login

The name of the view to redirect to when the user needs to log in

ckan.auth.reveal_private_datasets

Default value: False

Determines whether unauthorised requests for private datasets should have the existence of the datasets revealed (True) or hidden (False). If True, then unauthenticated requests will be redirected to the login page, and redirected back to the dataset after logging in, while authenticated but unauthorised requests will receive HTTP 403 Forbidden. If False, all unauthorised requests will receive HTTP 404 Not Found. Default is False.

ckan.auth.enable_cookie_auth_in_api

Default value: True

When set to False, cookie-based authentication is entirely ignored in all API requests, and authentication must be always done using API Tokens. Note that this will break some existing JS modules from the frontend that perform API calls, so it should be used with caution.

ckan.auth.route_after_login

Default value: dashboard.datasets

Allows to customize the route that the user will get redirected to after a successful login.

CSRF Protection

WTF_CSRF_ENABLED

Default value: True

Set to False to disable all CSRF protection.

WTF_CSRF_CHECK_DEFAULT

Default value: True

When using the CSRF protection extension, this controls whether every view is protected by default.

WTF_CSRF_SECRET_KEY

Default value: none

Random data for generating secure tokens. If not provided, the value of SECRET_KEY will be used.

WTF_CSRF_METHODS

Default value: POST PUT PATCH DELETE

HTTP methods to protect from CSRF.

WTF_CSRF_FIELD_NAME

Default value: _csrf_token

Name of the form field and session key that holds the CSRF token.

WTF_CSRF_HEADERS

Default value: X-CSRFToken X-CSRF-Token

HTTP headers to search for CSRF token when it is not provided in the form.

WTF_CSRF_TIME_LIMIT

Default value: 3600

Max age in seconds for CSRF tokens. This value is capped by the lifetime of the session.

WTF_CSRF_SSL_STRICT

Default value: True

Whether to enforce the same origin policy by checking that the referrer matches the host. Only applies to HTTPS requests. Default is True.

WTF_I18N_ENABLED

Default value: True

Set to False to disable Flask-Babel I18N support. Also set to False if you want to use WTForms’s built-in messages directly, see more info here.

ckan.csrf_protection.ignore_extensions

Default value: True

Exempt plugins blueprints from CSRF protection.

Warning

This feature will be deprecated in future versions.

Flask-Login Remember me cookie settings

REMEMBER_COOKIE_NAME

Default value: remember_token

The name of the cookie to store the “remember me” information in.

REMEMBER_COOKIE_DURATION

Default value: 31536000

The amount of time before the cookie expires, as a datetime.timedelta object or integer seconds.

REMEMBER_COOKIE_DOMAIN

Default value: none

If the “Remember Me” cookie should cross domains, set the domain value here (i.e. .example.com would allow the cookie to be used on all subdomains of example.com).

REMEMBER_COOKIE_PATH

Default value: /

Limits the “Remember Me” cookie to a certain path.

REMEMBER_COOKIE_SECURE

Default value: False

Restricts the “Remember Me” cookie’s scope to secure channels (typically HTTPS).

REMEMBER_COOKIE_HTTPONLY

Default value: True

Prevents the “Remember Me” cookie from being accessed by client-side scripts.

REMEMBER_COOKIE_REFRESH_EACH_REQUEST

Default value: False

If set to True the cookie is refreshed on every request, which bumps the lifetime. Works like Flask’s SESSION_REFRESH_EACH_REQUEST.

REMEMBER_COOKIE_SAMESITE

Default value: None

Restricts the “Remember Me” cookie to first-party or same-site context.

API Token Settings

api_token.nbytes

Example:

api_token.nbytes = 20

Default value: 32

Number of bytes used to generate unique id for API Token.

api_token.jwt.encode.secret

Example:

api_token.jwt.encode.secret = file:/path/to/private/key

Default value: none

A key suitable for the chosen algorithm(api_token.jwt.algorithm):

• for asymmetric algorithms(RS256): path to private key with file: prefix. I.e file:/path/private/key

• for symmetric algorithms(HS256): plain string, sufficiently long for security with string: prefix. I.e string:123abc...

Note

For symmetric algorithms this value must be identical to api_token.jwt.decode.secret. The algorithm used is controlled by the api_token.jwt.algorithm option.

Value must have prefix, which defines its type. Supported prefixes are:

• string: - Plain string, will be used as is.

• file: - Path to file. Content of the file will be used as key.

If not provided, "string:" + SECRET_KEY is used.

api_token.jwt.decode.secret

Example:

api_token.jwt.decode.secret = file:/path/to/public/key.pub

Default value: none

A key suitable for the chosen algorithm(api_token.jwt.algorithm):

• for asymmetric algorithms(RS256): path to public key with file: prefix. I.e file:/path/public/key.pub

• for symmetric algorithms(HS256): plain string, sufficiently long for security with string: prefix. I.e string:123abc...

Note

For symmetric algorithms this value must be identical to api_token.jwt.encode.secret. The algorithm used is defined by the api_token.jwt.algorithm option.

Value must have prefix, which defines it’s type. Supported prefixes are:

• string: - Plain string, will be used as is.

• file: - Path to file. Content of the file will be used as key.

If not provided, "string:" + SECRET_KEY is used.

api_token.jwt.algorithm

Example:

api_token.jwt.algorithm = RS256

Default value: HS256

Algorithm to sign the token with, e.g. “ES256”, “RS256”

Depending on the algorithm, additional restrictions may apply to api_token.jwt.decode.secret and api_token.jwt.encode.secret. For example, RS256 implies that api_token.jwt.encode.secret contains RSA private key and api_token.jwt.decode.secret contains public key. Whereas HS256(default value) requires both api_token.jwt.decode.secret and api_token.jwt.encode.secret to have exactly the same value.

Search Settings

ckan.site_id

Example:

ckan.site_id = my_ckan_instance

Default value: default

CKAN uses Solr to index and search packages. The search index is linked to the value of the ckan.site_id, so if you have more than one CKAN instance using the same solr_url, they will each have a separate search index as long as their ckan.site_id values are different. If you are only running a single CKAN instance then this can be ignored.

Note

If you change this value, you need to rebuild the search index.

solr_url

Example:

solr_url = http://solr.okfn.org:8983/solr/ckan-schema-2.0

Default value: none

This configures the Solr server used for search. The Solr schema found at that URL must be one of the ones in ckan/config/solr (generally the most recent one). A check of the schema version number occurs when CKAN starts.

Optionally, solr_user and solr_password can also be configured to specify HTTP Basic authentication details for all Solr requests.

Note

If you change this value, you need to rebuild the search index.

solr_user

Default value: none

User to use in HTTP Basic Authentication when connecting to Solr

solr_password

Default value: none

Password to use in HTTP Basic Authentication when connecting to Solr

ckan.search.remove_deleted_packages

Default value: True

By default, deleted datasets are removed from the search index so are no longer available in searches. To keep them in the search index, set this setting to False. This will enable the include_deleted parameter in the ckan.logic.action.get.package_search() API action.

ckan.search.solr_commit

Default value: True

Make ckan commit changes solr after every dataset update change. Turn this to false if on solr 4.0 and you have automatic (soft)commits enabled to improve dataset update/create speed (however there may be a slight delay before dataset gets seen in results).

ckan.search.solr_allowed_query_parsers

Example:

ckan.search.solr_allowed_query_parsers = ['bool', 'knn']

Default value: none

Local parameters are not allowed when passing queries to Solr. An exception to this is when passing local parameters for special query parsers, that need to be enabled explicitly using this config option. For instance, the example provided would allow sending queries like the following::

search_params[“q”] = “{!bool must=test}…” search_params[“q”] = “{!knn field=vector topK=10}…”

ckan.search.show_all_types

Example:

ckan.search.show_all_types = dataset

Default value: dataset

Controls whether a search page (e.g. /dataset) should also show custom dataset types. The default is false meaning that no search page for any type will show other types. true will show other types on the /dataset search page. Any other value (e.g. dataset or document will be treated as a dataset type and that type’s search page will show datasets of all types.

ckan.search.default_include_private

Default value: True

Controls whether the default search page (/dataset) should include private datasets visible to the current user or only public datasets visible to everyone.

ckan.search.default_package_sort

Example:

ckan.search.default_package_sort = name asc

Default value: score desc, metadata_modified desc

Controls whether the default search page (/dataset) should different sorting parameter by default when the request does not specify sort.

search.facets.limit

Example:

search.facets.limit = 100

Default value: 50

Sets the default number of searched facets returned in a query.

search.facets.default

Example:

search.facets.default = 10

Default value: 10

Default number of facets shown in search results.

ckan.extra_resource_fields

Example:

ckan.extra_resource_fields = alt_url

Default value: none

List of the extra resource fields that would be used when searching.

ckan.search.rows_max

Example:

ckan.search.rows_max = 1000

Default value: 1000

Maximum allowed value for rows returned. Specifically this limits:

• package_search’s rows parameter

• group_show and organization_show’s number of datasets returned when specifying include_datasets=true

ckan.group_and_organization_list_max

Example:

ckan.group_and_organization_list_max = 1000

Default value: 1000

Maximum number of groups/organizations returned when listing them. Specifically this limits:

• group_list’s limit when all_fields=false

• organization_list’s limit when all_fields=false

ckan.group_and_organization_list_all_fields_max

Example:

ckan.group_and_organization_list_all_fields_max = 100

Default value: 25

Maximum number of groups/organizations returned when listing them in detail. Specifically this limits:

• group_list’s limit when all_fields=true

• organization_list’s limit when all_fields=true

solr_timeout

Example:

solr_timeout = 120

Default value: 60

The option defines the timeout in seconds until giving up on a request. Raising this value might help you if you encounter a timeout exception.

Redis Settings

ckan.redis.url

Example:

ckan.redis.url = redis://localhost:7000/1

Default value: redis://localhost:6379/0

URL to your Redis instance, including the database to be used.

CORS Settings

ckan.cors.origin_allow_all

Example:

ckan.cors.origin_allow_all = true

Default value: False

This setting must be present to enable CORS. If True, all origins will be allowed (the response header Access-Control-Allow-Origin is set to ‘*’). If False, only origins from the ckan.cors.origin_whitelist setting will be allowed.

ckan.cors.origin_whitelist

Example:

ckan.cors.origin_whitelist = http://www.myremotedomain1.com http://myremotedomain1.com

Default value: none

A space separated list of allowable origins. This setting is used when ckan.cors.origin_allow_all = False.

Plugins Settings

ckan.plugins

Example:

ckan.plugins = activity scheming_datasets datatables_view datastore xloader

Default value: none

Specify which CKAN plugins are to be enabled.

Warning

If you specify a plugin but have not installed the code, CKAN will not start.

Format as a space-separated list of the plugin names. The plugin name is the key in the [ckan.plugins] section of the extension’s setup.py. For more information on plugins and extensions, see Extending guide.

Note

The order of the plugin names in the configuration file influences the order that CKAN will load the plugins in. As long as each plugin class is implemented in a separate Python module (i.e. in a separate Python source code file), the plugins will be loaded in the order given in the configuration file.

When multiple plugins are implemented in the same Python module, CKAN will process the plugins in the order that they’re given in the config file, but as soon as it reaches one plugin from a given Python module, CKAN will load all plugins from that Python module, in the order that the plugin classes are defined in the module.

For simplicity, we recommend implementing each plugin class in its own Python module.

Plugin loading order can be important, for example for plugins that add custom template files: templates found in template directories added earlier will override templates in template directories added later.

Todo

Fix CKAN’s plugin loading order to simply load all plugins in the order they’re given in the config file, regardless of which Python modules they’re implemented in.

ckan.resource_proxy.timeout

Default value: 5

Timeout in seconds to use on Resource Proxy requests.

Front-End Settings

ckan.site_title

Example:

ckan.site_title = Open Data Scotland

Default value: CKAN

This sets the name of the site, as displayed in the CKAN web interface.

ckan.site_description

Example:

ckan.site_description = The easy way to get, use and share data

Default value: none

This is for a description, or tag line for the site, as displayed in the header of the CKAN web interface.

ckan.site_intro_text

Example:

ckan.site_intro_text = Nice introductory paragraph about CKAN or the site in general.

Default value: none

This is for an introductory text used in the default template’s index page.

ckan.site_logo

Example:

ckan.site_logo = /images/ckan_logo_fullname_long.png

Default value: /base/images/ckan-logo.png

This sets the logo used in the title bar.

ckan.site_about

Example:

ckan.site_about = A _community-driven_ catalogue of _open data_ for the Greenfield area.

Default value: none

Format tips:

• multiline strings can be used by indenting following lines

• the format is Markdown

Note

Whilst the default text is translated into many languages (switchable in the page footer), the text in this configuration option will not be translatable. For this reason, it’s better to overload the snippet in home/snippets/about_text.html. For more information, see Theming guide.

ckan.theme

Example:

ckan.theme = my-extension/theme-asset

Default value: css/main

With this option, instead of using the default css/main asset with the theme, you can use your own.

ckan.favicon

Example:

ckan.favicon = http://okfn.org/wp-content/themes/okfn-master-wordpress-theme/images/favicon.ico

Default value: /base/images/ckan.ico

This sets the site’s favicon. This icon is usually displayed by the browser in the tab heading and bookmark.

ckan.datasets_per_page

Example:

ckan.datasets_per_page = 10

Default value: 20

This controls the pagination of the dataset search results page. This is the maximum number of datasets viewed per page of results.

package_hide_extras

Example:

package_hide_extras = my_private_field other_field

Default value: none

This sets a space-separated list of extra field key values which will not be shown on the dataset read page.

Warning

While this is useful to e.g. create internal notes, it is not a security measure. The keys will still be available via the API and in revision diffs.

ckan.recaptcha.publickey

Default value: none

The public key for your reCAPTCHA account, for example:

ckan.recaptcha.publickey = 6Lc...-KLc

To get a reCAPTCHA account, sign up at: http://www.google.com/recaptcha

ckan.recaptcha.privatekey

Default value: none

The private key for your reCAPTCHA account, for example:

ckan.recaptcha.privatekey = 6Lc...-jP

Setting both ckan.recaptcha.publickey and ckan.recaptcha.privatekey adds captcha to the user registration form. This has been effective at preventing bots registering users and creating spam packages.

ckan.featured_groups

Example:

ckan.featured_groups = group_one

Default value: none

Defines a list of group names or group ids. This setting is used to display a group and datasets on the home page in the default templates (1 group and 2 datasets are displayed).

ckan.featured_orgs

Example:

ckan.featured_orgs = org_one

Default value: none

Defines a list of organization names or ids. This setting is used to display an organization and datasets on the home page in the default templates (1 group and 2 datasets are displayed).

ckan.default_group_sort

Example:

ckan.default_group_sort = name

Default value: title

Defines if some other sorting is used in group_list and organization_list by default when the request does not specify sort.

ckan.gravatar_default

Example:

ckan.gravatar_default = disabled

Default value: identicon

This controls the default gravatar style. Gravatar is used by default when a user has not set a custom profile picture, but it can be turn completely off by setting this option to “disabled”. In that case, a placeholder image will be shown instead, which can be customized overriding the templates/user/snippets/placeholder.html template.

ckan.debug_supress_header

Example:

ckan.debug_supress_header = false

Default value: False

This configs if the debug information showing the controller and action receiving the request being is shown in the header.

Note

This info only shows if debug is set to True.

ckan.site_custom_css

Default value: none

Custom CSS directives to include on all CKAN pages.

Resource Views Settings

ckan.views.default_views

Example:

ckan.views.default_views = image_view webpage_view datatables_view

Default value: image_view datatables_view

Defines the resource views that should be created by default when creating or updating a dataset. From this list only the views that are relevant to a particular resource format will be created. This is determined by each individual view.

If not present (or commented), the default value is used. If left empty, no default views are created.

Note

You must have the relevant view plugins loaded on the ckan.plugins setting to be able to create the default views, eg:: ckan.plugins = image_view webpage_view geo_view datatables_view … ckan.views.default_views = image_view webpage_view datatables_view

Theming Settings

ckan.template_title_delimiter

Example:

ckan.template_title_delimiter = |

Default value: -

This sets the delimiter between the site’s subtitle (if there’s one) and its title, in HTML’s <title>.

extra_template_paths

Example:

extra_template_paths = /home/okfn/brazil_ckan_config/templates

Default value: none

Use this option to specify where CKAN should look for additional templates, before reverting to the ckan/templates folder. You can supply more than one folder, separating the paths with a comma (,).

For more information on theming, see Theming guide.

extra_public_paths

Example:

extra_public_paths = /home/okfn/brazil_ckan_config/public

Default value: none

To customise the display of CKAN you can supply replacements for static files such as HTML, CSS, script and PNG files. Use this option to specify where CKAN should look for additional files, before reverting to the ckan/public folder. You can supply more than one folder, separating the paths with a comma (,).

For more information on theming, see Theming guide.

ckan.base_public_folder

Example:

ckan.base_public_folder = public

Default value: public

This config option is used to configure the base folder for static files used by CKAN core. Starting CKAN 2.11 it only accepts: public as a value. (This variable is kept for backwards compatibility when updating Bootstrap versions.)

ckan.base_templates_folder

Example:

ckan.base_templates_folder = templates

Default value: templates

This config option is used to configure the base folder for templates used by CKAN core. Starting CKAN 2.11 it only accepts: templates as a value. (This variable is kept for backwards compatibility when updating Bootstrap versions.)

ckan.default.package_type

Default value: dataset

Default type of dataset that will be used in the UI links (eg. “New Dataset”).

Use this option to change the dataset type that is used site-wide. Only existing dataset types can be used as a value for this option. Upon setting a custom value, the following happens:

• all new datasets have their type field set to the custom value(if no explicit value provided)

• all labels(e.g. “Create a Dataset”, “My datasets”, “Search datasets..”) are adapted to the custom value

• all default links(e.g. /dataset/new, /dataset/<name>/resource) are adapted to the custom value

If labels require additional changes, register a chained helpers for humanize_entity_type(). For example, setting a dataset type camel_photo as default, will turn the “Datasets” link in the header into “Camel-photos”. If “Camel Photos” is expected, the code below can be used:

@p.toolkit.chained_helper
def humanize_entity_type(next_helper: Callable[..., Any],
                         entity_type: str, object_type: str, purpose: str):
    if purpose == "main nav":
        return "Camel Photos"

    return next_helper(entity_type, object_type, purpose)

See humanize_entity_type() for additional details.

ckan.default.group_type

Default value: group

Default type of group that used in UI links(eg. “New Group” button, “Groups” link in header)

Same as ckan.default.package_type, but for groups.

ckan.default.organization_type

Default value: organization

Default type of group that used in UI links(eg. “New Organization” button, “Organizations” link in header)

Same as ckan.default.package_type, but for organizations.

Storage Settings

ckan.storage_path

Example:

ckan.storage_path = /var/lib/ckan/default

Default value: none

This defines the location of where CKAN will store all uploaded data.

ckan.max_resource_size

Example:

ckan.max_resource_size = 100

Default value: 10

The maximum in megabytes a resources upload can be.

ckan.max_image_size

Example:

ckan.max_image_size = 10

Default value: 2

The maximum in megabytes an image upload can be.

Uploader Settings

ckan.upload.user.types

Example:

ckan.upload.user.types = image text

Default value: image

File types allowed to upload as user’s avatar. No restrictions applied when empty

ckan.upload.user.mimetypes

Example:

ckan.upload.user.mimetypes = image/png text/svg

Default value: image/png image/gif image/jpeg

File MIMETypes allowed to upload as user’s avatar. No restrictions applied when empty

ckan.upload.group.types

Example:

ckan.upload.group.types = image text

Default value: image

File types allowed to upload as group image. No restrictions applied when empty

ckan.upload.group.mimetypes

Example:

ckan.upload.group.mimetypes = image/png text/svg

Default value: image/png image/gif image/jpeg

File MIMETypes allowed to upload as group image. No restrictions applied when empty

Webassets Settings

ckan.webassets.path

Example:

ckan.webassets.path = /var/lib/ckan/webassets

Default value: none

In order to increase performance, static assets (CSS and JS files) included via an asset tag inside templates are compiled only once, when the asset is used for the first time. All subsequent requests to the asset will use the existing file. CKAN stores the compiled webassets in the file system, in the path specified by this config option.

ckan.webassets.url

Example:

ckan.webassets.url = /serve/assets/from/here

Default value: /webassets

URL path for endpoint that serves webassets.

ckan.webassets.use_x_sendfile

Example:

ckan.webassets.use_x_sendfile = True

Default value: False

When serving static files, if this setting is True, the applicatin will set the X-Sendfile header instead of serving the files directly with Flask. This will increase performance when serving the assets, but it requires that the web server (eg Nginx) supports the X-Sendfile header. See X-Sendfile for more information.

User Settings

ckan.user_list_limit

Example:

ckan.user_list_limit = 50

Default value: 20

This controls the number of users to show in the Users list. By default, it shows 20 users.

ckan.user_reset_landing_page

Example:

ckan.user_reset_landing_page = dataset

Default value: home.index

This controls the page where users will be sent after requesting a password reset. This is ordinarily the home page, but specific sites may prefer somewhere else.

Activity Streams Settings

ckan.activity_streams_enabled

Example:

ckan.activity_streams_enabled = false

Default value: True

Turns on and off the activity streams used to track changes on datasets, groups, users, etc. The activity feature has been moved to a separate activity plugin. To keep showing the activities in the UI and enable the activity related API actions you need to add the activity plugin to the ckan.plugins config option.

ckan.activity_streams_email_notifications

Example:

ckan.activity_streams_email_notifications = false

Default value: False

Turns on and off the activity streams’ email notifications. You’d also need to setup a cron job to send the emails. For more information, visit Email notifications.

ckan.activity_list_limit

Example:

ckan.activity_list_limit = 31

Default value: 31

This controls the number of activities to show in the Activity Stream.

ckan.activity_list_limit_max

Example:

ckan.activity_list_limit_max = 100

Default value: 100

Maximum allowed value for Activity Stream limit parameter.

ckan.email_notifications_since

Example:

ckan.email_notifications_since = 2 days

Default value: 2 days

Email notifications for events older than this time delta will not be sent. Accepted formats: ‘2 days’, ‘14 days’, ‘4:35:00’ (hours, minutes, seconds), ‘7 days, 3:23:34’, etc.

ckan.hide_activity_from_users

Example:

ckan.hide_activity_from_users = sysadmin

Default value: none

Hides activity from the specified users from activity stream. If unspecified, it’ll use ckan.site_id to hide activity by the site user. The site user is a sysadmin user on every ckan user with a username that’s equal to ckan.site_id. This user is used by ckan for performing actions from the command-line.

Feeds Settings

ckan.feeds.author_name

Example:

ckan.feeds.author_name = Michael Jackson

Default value: none

This controls the feed author’s name. If unspecified, it’ll use ckan.site_id.

ckan.feeds.author_link

Example:

ckan.feeds.author_link = http://okfn.org

Default value: none

This controls the feed author’s link. If unspecified, it’ll use ckan.site_url.

ckan.feeds.authority_name

Example:

ckan.feeds.authority_name = http://okfn.org

Default value: none

The domain name or email address of the default publisher of the feeds and elements. If unspecified, it’ll use ckan.site_url.

ckan.feeds.date

Example:

ckan.feeds.date = 2012-03-22

Default value: none

A string representing the default date on which the authority_name is owned by the publisher of the feed.

ckan.feeds.limit

Default value: 20

Number of items returned in the feeds

Internationalisation Settings

ckan.locale_default

Example:

ckan.locale_default = de

Default value: en

Use this to specify the locale (language of the text) displayed in the CKAN Web UI. This requires a suitable mo file installed for the locale in the ckan/i18n. For more information on internationalization, see Translating CKAN. If you don’t specify a default locale, then it will default to the first locale offered, which is by default English (alter that with ckan.locales_offered and ckan.locales_filtered_out.

ckan.locales_offered

Example:

ckan.locales_offered = en de fr

Default value: none

By default, all locales found in the ckan/i18n directory will be offered to the user. To only offer a subset of these, list them under this option. The ordering of the locales is preserved when offered to the user.

ckan.locales_filtered_out

Example:

ckan.locales_filtered_out = pl ru

Default value: none

If you want to not offer particular locales to the user, then list them here to have them removed from the options.

ckan.locale_order

Example:

ckan.locale_order = fr de

Default value: none

If you want to specify the ordering of all or some of the locales as they are offered to the user, then specify them here in the required order. Any locales that are available but not specified in this option, will still be offered at the end of the list.

ckan.i18n_directory

Example:

ckan.i18n_directory = /opt/locales/i18n/

Default value: none

By default, the locales are searched for in the ckan/i18n directory. Use this option if you want to use another folder.

ckan.i18n.extra_directory

Example:

ckan.i18n.extra_directory = /opt/ckan/extra_translations/

Default value: none

If you wish to add extra translation strings and have them merged with the default ckan translations at runtime you can specify the location of the extra translations using this option.

ckan.i18n.extra_gettext_domain

Example:

ckan.i18n.extra_gettext_domain = mydomain

Default value: none

You can specify the name of the gettext domain of the extra translations. For example if your translations are stored as i18n/<locale>/LC_MESSAGES/somedomain.mo you would want to set this option to somedomain

ckan.i18n.extra_locales

Example:

ckan.i18n.extra_locales = fr es de

Default value: none

If you have set an extra i18n directory using ckan.i18n.extra_directory, you should specify the locales that have been translated in that directory in this option.

ckan.i18n.rtl_languages

Example:

ckan.i18n.rtl_languages = he ar fa_IR

Default value: he ar fa_IR

Allows to modify the right-to-left languages

ckan.i18n.rtl_theme

Example:

ckan.i18n.rtl_theme = my-extension/my-custom-rtl-asset

Default value: css/main-rtl

Allows to override the default rtl asset used for the languages defined in ckan.i18n.rtl_languages.

ckan.display_timezone

Example:

ckan.display_timezone = Europe/Zurich

Default value: UTC

By default, all datetimes are considered to be in the UTC timezone. Use this option to change the displayed dates on the frontend. Internally, the dates are always saved as UTC. This option only changes the way the dates are displayed.

The valid values for this options [can be found at pytz](http://pytz.sourceforge.net/#helpers) (pytz.all_timezones). You can specify the special value server to use the timezone settings of the server, that is running CKAN.

ckan.root_path

Example:

ckan.root_path = /my/custom/path/{{LANG}}/foo

Default value: none

This setting is used to construct URLs inside CKAN. It specifies two things:

• At which path CKAN is mounted: By default it is assumed that CKAN is mounted at /, i.e. at the root of your web server. If you have configured your web server to serve CKAN from a different mount point then you need to duplicate that setting here.

• Where the locale is added to an URL: By default, URLs are formatted as /some/url when using the default locale, or /de/some/url when using the de locale, for example. When ckan.root_path is set it must include the string {{LANG}}, which will be replaced by the locale.

Important

The setting must contain {{LANG}} exactly as written here. Do not add spaces between the brackets.

See also

The host of your CKAN installation can be set via ckan.site_url.

The CKAN repoze config file who.ini file will also need to be edited by adding the path prefix to the options in the [plugin:friendlyform] section: login_form_url, post_login_url and post_logout_url. Do not change the login/logout_handler_path options.

ckan.resource_formats

Example:

ckan.resource_formats = /path/to/resource_formats

Default value: /<CKAN_ROOT>/ckan/config/resource_formats.json

The purpose of this file is to supply a thorough list of resource formats and to make sure the formats are normalized when saved to the database and presented.

The format of the file is a JSON object with following format:

["Format", "Description", "Mimetype", ["List of alternative representations"]]

Please look in ckan/config/resource_formats.json for full details and and as an example.

Form Settings

ckan.dataset.create_on_ui_requires_resources

Example:

ckan.dataset.create_on_ui_requires_resources = false

Default value: True

If False, there is no need to add any resources when creating a new dataset.

package_new_return_url

Default value: none

The URL to redirect the user to after they’ve submitted a new package form, example:

package_new_return_url = http://datadotgc.ca/new_dataset_complete?name=<NAME>

This is useful for integrating CKAN’s new dataset form into a third-party interface, see Form Integration.

The <NAME> string is replaced with the name of the dataset created.

package_edit_return_url

Default value: none

The URL to redirect the user to after they’ve submitted an edit package form, example:

package_edit_return_url = http://datadotgc.ca/dataset/<NAME>

This is useful for integrating CKAN’s edit dataset form into a third-party interface, see Form Integration.

The <NAME> string is replaced with the name of the dataset that was edited.

licenses_group_url

Example:

licenses_group_url = file:///path/to/my/local/json-list-of-licenses.json

Default value: none

A url pointing to a JSON file containing a list of license objects. This list determines the licenses offered by the system to users, for example when creating or editing a dataset.

This is entirely optional - by default, the system will use an internal cached version of the CKAN list of licenses available from the http://licenses.opendefinition.org/licenses/groups/ckan.json.

More details about the license objects - including the license format and some example license lists - can be found at the Open Licenses Service.

Email settings

smtp.server

Example:

smtp.server = smtp.example.com:587

Default value: localhost

The SMTP server to connect to when sending emails with optional port.

smtp.starttls

Example:

smtp.starttls = true

Default value: False

Whether or not to use STARTTLS when connecting to the SMTP server.

smtp.user

Example:

smtp.user = username@example.com

Default value: none

The username used to authenticate with the SMTP server.

smtp.password

Example:

smtp.password = yourpass

Default value: none

The password used to authenticate with the SMTP server.

smtp.mail_from

Example:

smtp.mail_from = ckan@example.com

Default value: none

The email address that emails sent by CKAN will come from. Note that, if left blank, the SMTP server may insert its own.

smtp.reply_to

Example:

smtp.reply_to = noreply.example.com

Default value: none

The email address that will be used if someone attempts to reply to a system email. If left blank, no Reply-to will be added to the email and the value of smtp.mail_from will be used.

email_to

Example:

email_to = errors@example.com

Default value: none

This controls where the error messages will be sent to.

error_email_from

Example:

error_email_from = ckan-errors@example.com

Default value: none

This controls from which email the error messages will come from.

Background Job Settings

ckan.jobs.timeout

Default value: 180

The option defines the timeout in seconds until giving up on a job

Resource Proxy settings

ckan.resource_proxy.max_file_size

Example:

ckan.resource_proxy.max_file_size = 1048576

Default value: 1048576

This sets the upper file size limit for in-line previews. Increasing the value allows CKAN to preview larger files (e.g. PDFs) in-line; however, a higher value might cause time-outs, or unresponsive browsers for CKAN users with lower bandwidth.

ckan.resource_proxy.chunk_size

Example:

ckan.resource_proxy.chunk_size = 8192

Default value: 4096

This sets size of the chunk to read and write when proxying. Raising this value might save some CPU cycles. It makes no sense to lower it below the page size, which is default.

text_view settings

ckan.preview.text_formats

Example:

ckan.preview.text_formats = txt plain

Default value: text/plain txt plain

Space-delimited list of plain text based resource formats that will be rendered by the Text view plugin

ckan.preview.xml_formats

Example:

ckan.preview.xml_formats = xml rdf rss

Default value: xml rdf rdf+xml owl+xml atom rss

Space-delimited list of XML based resource formats that will be rendered by the Text view plugin

ckan.preview.json_formats

Example:

ckan.preview.json_formats = json

Default value: json

Space-delimited list of JSON based resource formats that will be rendered by the Text view plugin

ckan.preview.jsonp_formats

Default value: jsonp

Space-delimited list of JSONP based resource formats that will be rendered by the Text view plugin

image_view settings

ckan.preview.image_formats

Example:

ckan.preview.image_formats = png jpeg jpg gif

Default value: png jpeg jpg gif

Space-delimited list of image-based resource formats that will be rendered by the Image view plugin

datatables_view settings

ckan.datatables.page_length_choices

Example:

ckan.datatables.page_length_choices = 20 50 100 500 1000 5000

Default value: 20 50 100 500 1000

Space-delimited list of the choices for the number of rows per page, with the lowest value being the default initial value.

Note

On larger screens, DataTables view will attempt to fill the table with as many rows that can fit using the lowest closest choice.

ckan.datatables.state_saving

Example:

ckan.datatables.state_saving = false

Default value: True

Enable or disable state saving. When enabled, DataTables view will store state information such as pagination position, page length, row selection/s, column visibility/ordering, filtering and sorting using the browser’s localStorage. When the end user reloads the page, the table’s state will be altered to match what they had previously set up.

This also enables/disables the “Reset” and “Share current view” buttons. “Reset” discards the saved state. “Share current view” base-64 encodes the state and passes it as a url parameter, acting like a “saved search” that can be used for embedding and sharing table searches.

ckan.datatables.state_duration

Example:

ckan.datatables.state_duration = 86400

Default value: 7200

Duration (in seconds) for which the saved state information is considered valid. After this period has elapsed, the table’s state will be returned to the default, and the state cleared from the browser’s localStorage.

Note

The value 0 is a special value as it indicates that the state can be stored and retrieved indefinitely with no time limit.

ckan.datatables.data_dictionary_labels

Example:

ckan.datatables.data_dictionary_labels = false

Default value: True

Enable or disable data dictionary integration. When enabled, a column’s data dictionary label will be used in the table header. A tooltip for each column with data dictionary information will also be integrated into the header.

ckan.datatables.ellipsis_length

Example:

ckan.datatables.ellipsis_length = 100

Default value: 100

The maximum number of characters to show in a cell before it is truncated. An ellipsis (…) will be added at the truncation point and the full text of the cell will be available as a tooltip. This value can be overridden at the resource level when configuring a DataTables resource view.

Note

The value 0 is a special value as it indicates that the column’s width will be determined by the column name, and cell content will word-wrap.

ckan.datatables.date_format

Example:

ckan.datatables.date_format = YYYY-MM-DD dd ww

Default value: llll

The moment.js date format to use to convert raw timestamps to a user-friendly date format using CKAN’s current locale language code. This value can be overridden at the resource level when configuring a DataTables resource view.

Note

The value NONE is a special value as it indicates that no date formatting will be applied and the raw ISO-8601 timestamp will be displayed.

ckan.datatables.default_view

Example:

ckan.datatables.default_view = list

Default value: table

Indicates the default view mode of the DataTable (valid values: table or list). Table view is the typical grid layout, with horizontal scrolling. List view is a responsive table, automatically hiding columns as required to fit the browser viewport. In addition, list view allows the user to view, copy and print the details of a specific row. This value can be overridden at the resource level when configuring a DataTables resource view.

ckan.datatables.null_label

Example:

ckan.datatables.null_label = N/A

Default value: none

The option defines the label used to display NoneType values for the front-end. This should be a string and can be translated via po files.

Datastore settings

ckan.datastore.write_url

Example:

ckan.datastore.write_url = postgresql://ckanuser:pass@localhost/datastore

Default value: postgresql://ckan_default:pass@localhost/datastore_default

The database connection to use for writing to the datastore (this can be ignored if you’re not using the DataStore extension). Note that the database used should not be the same as the normal CKAN database. The format is the same as in sqlalchemy.url.

ckan.datastore.read_url

Example:

ckan.datastore.read_url = postgresql://readonlyuser:pass@localhost/datastore

Default value: postgresql://datastore_default:pass@localhost/datastore_default

The database connection to use for reading from the datastore (this can be ignored if you’re not using the DataStore extension). The database used must be the same used in ckan.datastore.write_url, but the user should be one with read permissions only. The format is the same as in sqlalchemy.url.

ckan.datastore.sqlsearch.allowed_functions_file

Example:

ckan.datastore.sqlsearch.allowed_functions_file = /path/to/my_allowed_functions.txt

Default value: /<CKAN_ROOT>/ckanext/datastore/allowed_functions.txt

Allows to define the path to a text file listing the SQL functions that should be allowed to run on queries sent to the datastore_search_sql() function (if enabled, see ckan.datastore.sqlsearch.enabled). Function names should be listed one on each line, eg:

abbrev
abs
abstime
...

ckan.datastore.sqlsearch.enabled

Example:

ckan.datastore.sqlsearch.enabled = true

Default value: False

This option allows you to enable the datastore_search_sql() action function, and corresponding API endpoint.

This action function has protections from abuse including:

• parsing of the query to prevent unsafe functions from being called, see ckan.datastore.sqlsearch.allowed_functions_file

• parsing of the query to prevent multiple statements

• prevention of data modification by using a read-only database role

• use of explain to resolve tables accessed in the query to check against user permissions

• use of a statement timeout to prevent queries from running indefinitely

These protections offer some safety but are not designed to prevent all types of abuse. Depending on the sensitivity of private data in your datastore and the likelihood of abuse of your site you may choose to disable this action function or restrict its use with a IAuthFunctions plugin.

ckan.datastore.search.rows_default

Example:

ckan.datastore.search.rows_default = 1000

Default value: 100

Default number of rows returned by datastore_search, unless the client specifies a different limit (up to ckan.datastore.search.rows_max).

NB this setting does not affect datastore_search_sql.

ckan.datastore.search.rows_max

Example:

ckan.datastore.search.rows_max = 1000000

Default value: 32000

Maximum allowed value for the number of rows returned by the datastore.

Specifically this limits:

• datastore_search’s limit parameter.

• datastore_search_sql queries have this limit inserted.

ckan.datastore.sqlalchemy.<OPTION>

Default value: none

Custom sqlalchemy config parameters used to establish the DataStore database connection.

To get the list of all the available properties check the SQLAlchemy documentation

ckan.datastore.default_fts_lang

Example:

ckan.datastore.default_fts_lang = english

Default value: english

The default language used when creating full-text search indexes and querying them. It can be overwritten by the user by passing the “lang” parameter to “datastore_search” and “datastore_create”.

ckan.datastore.default_fts_index_method

Example:

ckan.datastore.default_fts_index_method = gist

Default value: gist

The default method used when creating full-text search indexes. Currently it can be “gin” or “gist”. Refer to PostgreSQL’s documentation to understand the characteristics of each one and pick the best for your instance.

Datapusher settings

ckan.datapusher.formats

Example:

ckan.datapusher.formats = csv xls

Default value: csv xls xlsx tsv application/csv application/vnd.ms-excel application/vnd.openxmlformats-officedocument.spreadsheetml.sheet ods application/vnd.oasis.opendocument.spreadsheet

File formats that will be pushed to the DataStore by the DataPusher. When adding or editing a resource which links to a file in one of these formats, the DataPusher will automatically try to import its contents to the DataStore.

ckan.datapusher.url

Example:

ckan.datapusher.url = http://127.0.0.1:8800/

Default value: none

DataPusher endpoint to use when enabling the datapusher extension. If you installed CKAN via Installing CKAN from package, the DataPusher was installed for you running on port 8800. If you want to manually install the DataPusher, follow the installation instructions.

ckan.datapusher.api_token

Default value: none

Starting from CKAN 2.10, DataPusher requires a valid API token to operate (see Authentication and API tokens), and will fail to start if this option is not set.

ckan.datapusher.callback_url_base

Example:

ckan.datapusher.callback_url_base = http://ckan:5000/

Default value: none

Alternative callback URL for DataPusher when performing a request to CKAN. This is useful on scenarios where the host where DataPusher is running can not access the public CKAN site URL.

ckan.datapusher.assume_task_stale_after

Example:

ckan.datapusher.assume_task_stale_after = 86400

Default value: 3600

In case a DataPusher task gets stuck and fails to recover, this is the minimum amount of time (in seconds) after a resource is submitted to DataPusher that the resource can be submitted again.