You can set many important options in the CKAN config file. By default, the configuration file is located at /etc/ckan/development.ini
or /etc/ckan/production.ini
. This section documents all of the config file settings, for reference.
Insert cross-ref to section about location of config file?
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_preview recline_preview
If the same option is set more than once in your config file, the last setting given in the file will override the others.
Example:
debug = False
Default value: False
This enables Pylons' interactive debugging tool, makes Fanstatic serve unminified JS and CSS files, and enables CKAN templates' debugging features.
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.
Example:
sqlalchemy.url = postgres://tester:pass@localhost/ckantest3
This defines the database that CKAN is to use. The format is:
sqlalchemy.url = postgres://USERNAME:PASSWORD@HOST/DBNAME
Example:
ckan.datastore.write_url = postgresql://ckanuser:pass@localhost/datastore
The database connection to use for writing to the datastore (this can be ignored if you're not using the datastore
). Note that the database used should not be the same as the normal CKAN database. The format is the same as in sqlalchemy.url
.
Example:
ckan.datastore.read_url = postgresql://readonlyuser:pass@localhost/datastore
The database connection to use for reading from the datastore (this can be ignored if you're not using the datastore
). 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
.
Example:
ckan.site_url = http://scotdata.ckan.net
Default value: (none)
The URL of your CKAN site. Many CKAN features that need an absolute URL to your site use this setting.
Warning
This setting should not have a trailing / on the end.
Example:
apikey_header_name = API-KEY
Default value: X-CKAN-API-Key
& Authorization
This allows another http header to be used to provide the CKAN API key. This is useful if network infrastructure blocks the Authorization header and X-CKAN-API-Key
is not suitable.
Example:
ckan.cache_expires = 2592000
Default value: 0
This sets Cache-Control
header's max-age value.
Example:
ckan.page_cache_enabled = True
Default value: False
This enables CKAN's built-in page caching.
Warning
Page caching is an experimental feature.
Example:
ckan.cache_enabled = True
Default value: None
Controls if we're caching CKAN's static files, if it's serving them.
Example:
ckan.static_max_age = 2592000
Default value: 3600
Controls CKAN static files' cache max age, if we're serving and caching them.
Example:
ckan.tracking_enabled = True
Default value: False
This controls if CKAN will track the site usage. For more info, read tracking
.
More information about how authorization works in CKAN can be found the authorization
section.
Example:
ckan.auth.anon_create_dataset = False
Default value: False
Allow users to create datasets without registering and logging in.
Example:
ckan.auth.create_unowned_dataset = False
Default value: True
Allow the creation of datasets not owned by any 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.
Example:
ckan.auth.user_create_groups = False
Default value: True
Allow users to create groups.
Example:
ckan.auth.user_create_organizations = False
Default value: True
Allow users to create organizations.
Example:
ckan.auth.user_delete_groups = False
Default value: True
Allow users to delete groups.
Example:
ckan.auth.user_delete_organizations = False
Default value: True
Allow users to delete organizations.
Example:
ckan.auth.create_user_via_api = False
Default value: False
Allow new user accounts to be created via the API.
Example:
ckan.auth.create_user_via_web = True
Default value: True
Allow new user accounts to be created via the Web.
Example:
ckan.site_id = my_ckan_instance
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.
Example:
ckan.simple_search = true
Default value: false
Switching this on tells CKAN search functionality to just query the database, (rather than using Solr). In this setup, search is crude and limited, e.g. no full-text search, no faceting, etc. However, this might be very useful for getting up and running quickly with CKAN.
Example:
solr_url = http://solr.okfn.org:8983/solr/ckan-schema-2.0
Default value: http://127.0.0.1:8983/solr
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.
Example:
ckan.search.automatic_indexing = true
Default value: true
Make all changes immediately available via the search after editing or creating a dataset. Default is true. If for some reason you need the indexing to occur asynchronously, set this option to false.
Note
This is equivalent to explicitly load the synchronous_search
plugin.
Example:
ckan.search.solr_commit = false
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).
Example:
ckan.search.show_all_types = true
Default value: false
Controls whether the default search page (/dataset
) should show only standard datasets or also custom dataset types.
Example:
search.facets.limit = 100
Default value: 50
Sets the default number of searched facets returned in a query.
Example:
search.facets.default = 10
Default number of facets shown in search results. Default 10.
Example:
ckan.extra_resource_fields = alt_url
Default value: None
List of the extra resource fields that would be used when searching.
Example:
ckan.plugins = disqus datapreview googleanalytics follower
Default value: stats text_preview recline_preview
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 extensions/index
.
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.
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.
Example:
ckan.datastore.enabled = True
Default value: False
Controls if the Data API link will appear in Dataset's Resource page.
Note
This setting only applies to the legacy templates.
Example:
ckanext.stats.cache_enabled = True
Default value: True
This controls if we'll use the 1 day cache for stats.
Example:
ckan.site_title = Open Data Scotland
Default value: CKAN
This sets the name of the site, as displayed in the CKAN web interface.
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.
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.
Example:
ckan.site_logo = /images/ckan_logo_fullname_long.png
Default value: (none)
This sets the logo used in the title bar.
Example:
ckan.site_about = A _community-driven_ catalogue of _open data_ for the Greenfield area.
Default value:
<p>CKAN is the world’s leading open-source data portal platform.</p>
<p>CKAN is a complete out-of-the-box software solution that makes data
accessible and usable – by providing tools to streamline publishing, sharing,
finding and using data (including storage of data and provision of robust data
APIs). CKAN is aimed at data publishers (national and regional governments,
companies and organizations) wanting to make their data open and available.</p>
<p>CKAN is used by governments and user groups worldwide and powers a variety
of official and community data portals including portals for local, national
and international government, such as the UK’s <a href="http://data.gov.uk">data.gov.uk</a>
and the European Union’s <a href="http://publicdata.eu/">publicdata.eu</a>,
the Brazilian <a href="http://dados.gov.br/">dados.gov.br</a>, Dutch and
Netherland government portals, as well as city and municipal sites in the US,
UK, Argentina, Finland and elsewhere.</p>
<p>CKAN: <a href="http://ckan.org/">http://ckan.org/</a><br />
CKAN Tour: <a href="http://ckan.org/tour/">http://ckan.org/tour/</a><br />
Features overview: <a href="http://ckan.org/features/">http://ckan.org/features/</a></p>
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/index
.
Example:
ckan.main_css = /base/css/my-custom.css
Default value: /base/css/main.css
With this option, instead of using the default main.css, you can use your own.
Example:
ckan.favicon = http://okfn.org/wp-content/themes/okfn-master-wordpress-theme/images/favicon.ico
Default value: /images/icons/ckan.ico
This sets the site's favicon. This icon is usually displayed by the browser in the tab heading and bookmark.
Example:
ckan.legacy_templates = True
Default value: False
This controls if the legacy genshi templates are used.
Note
This is only for legacy code, and shouldn't be used anymore.
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.
Example:
package_hide_extras = my_private_field other_field
Default value: (empty)
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.dataset.show_apps_ideas:
ckan.dataset.show_apps_ideas = false
Default value: true
When set to false, or no, this setting will hide the 'Apps, Ideas, etc' tab on the package read page. If the value is not set, or is set to true or yes, then the tab will shown.
Note
This only applies to the legacy Genshi-based templates
Example:
ckan.preview.direct = png jpg jpeg gif
Default value: png jpg jpeg gif
Defines the resource formats which should be embedded directly in an img
tag when previewing them.
Example:
ckan.preview.loadable = html htm rdf+xml owl+xml xml n3 n-triples turtle plain atom rss txt
Default value: html htm rdf+xml owl+xml xml n3 n-triples turtle plain atom rss txt
Defines the resource formats which should be loaded directly in an iframe
tag when previewing them if no data-viewer
can preview it.
If there is a page which allows you to download a dump of the entire catalogue then specify the URL here, so that it can be advertised in the web interface. For example:
ckan.dumps_url = http://ckan.net/dump/
For more information on using dumpfiles, see paster db
.
If there is a page which allows you to download a dump of the entire catalogue then specify the format here, so that it can be advertised in the web interface. dumps_format
is just a string for display. Example:
ckan.dumps_format = CSV/JSON
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
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.
Example:
ckan.featured_groups = group_one group_two
Default Value: (empty)
Defines a list of group names or group ids. This setting is used to display groups and datasets from each group on the home page in the default templates (2 groups and 2 datasets for each group are displayed).
Example:
ckan.featured_orgs = org_one org_two
Default Value: (empty)
Defines a list of organization names or ids. This setting is used to display organization and datasets from each group on the home page in the default templates (2 groups and 2 datasets for each group are displayed).
Example:
ckan.gravatar_default = monsterid
Default value: identicon
This controls the default gravatar avatar, in case the user has none.
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.
HTML content to be inserted just before </head>
tag (e.g. extra stylesheet)
Example:
ckan.template_head_end = <link rel="stylesheet" href="http://mysite.org/css/custom.css" type="text/css">
You can also have multiline strings. Just indent following lines. e.g.:
ckan.template_head_end =
<link rel="stylesheet" href="/css/extra1.css" type="text/css">
<link rel="stylesheet" href="/css/extra2.css" type="text/css">
Note
This is only for legacy code, and shouldn't be used anymore.
HTML content to be inserted just before </body>
tag (e.g. Google Analytics code).
Note
you can have multiline strings (just indent following lines)
Example (showing insertion of Google Analytics code):
ckan.template_footer_end = <!-- Google Analytics -->
<script src='http://www.google-analytics.com/ga.js' type='text/javascript'></script>
<script type="text/javascript">
try {
var pageTracker = _gat._getTracker("XXXXXXXXX");
pageTracker._setDomainName(".ckan.net");
pageTracker._trackPageview();
} catch(err) {}
</script>
<!-- /Google Analytics -->
Note
This is only for legacy code, and shouldn't be used anymore.
Example:
ckan.template_title_deliminater = |
Default value: -
This sets the delimiter between the site's subtitle (if there's one) and its title, in HTML's <title>
.
Example:
extra_template_paths = /home/okfn/brazil_ckan_config/templates
To customise the display of CKAN you can supply replacements for the Genshi template files. 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/index
.
Example:
extra_public_paths = /home/okfn/brazil_ckan_config/public
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/index
.
Example:
ckan.storage.bucket = ckan
Default value: None
This changes the bucket name for the uploaded files.
Example:
ckan.storage.max_content_length = 500000
Default value: 50000000
This defines the maximum content size, in bytes, for uploads.
Example:
ofs.impl = pairtree
Default value: None
Defines the storage backend used by CKAN: pairtree
for local storage, s3
for Amazon S3 Cloud Storage or google
for Google Cloud Storage. Note that each of these must be accompanied by the relevant settings for each backend described below.
Example:
ofs.storage_dir = /data/uploads/
Default value: None
Only used with the local storage backend. Use this to specify where uploaded files should be stored, and also to turn on the handling of file storage. The folder should exist, and will automatically be turned into a valid pairtree repository if it is not already.
Example:
ckan.storage.key_prefix = ckan-file/
Default value: file/
Only used with the local storage backend. This changes the prefix for the uploaded files.
Example:
ofs.aws_access_key_id = 022QF06E7MXBSH9DHM02
Default value: None
Only used with the Amazon S3 storage backend. Configure with your AWS Access Key ID.
Example:
ofs.aws_secret_access_key = kWcrlUX5JEDGM/LtmEENI/aVmYvHNif5zB+d9+ct
Default value: None
Only used with the Amazon S3 storage backend. Configure with your AWS Secret Access Key.
Example:
ofs.gs_access_key_id = GOOGTS7C7FUP3AIRVJTE
Default value: None
Only used with the Google storage backend. Configure with your Google Storage Access Key ID.
Example:
ofs.gs_secret_access_key = bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ
Default value: None
Only used with the Google storage backend. Configure with your Google Storage Secret Access Key.
- Example::
ckan.datapusher.formats = csv xls xlsx
Expand
- Example::
ckan.datapusher.url = http://datapusher.ckan.org/
Expand
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
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
.
Example:
ckan.activity_list_limit = 31
Default value: infinite
This controls the number of activities to show in the Activity Stream. By default, it shows everything.
Example:
ckan.email_notifications_since = 2 days
Default value: infinite
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.
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
.
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
.
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
.
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.
Example:
ckan.locale_default = de
Default value: en
(English)
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 i18n
. 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.
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.
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.
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.
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.
Example:
ckan.root_path = /my/custom/path/{{LANG}}/foo
Default value: (none)
By default, the URLs are formatted as /some/url
, when using the default locale, or /de/some/url
when using the "de" locale, for example. This lets you change this. You can use any path that you want, adding {{LANG}}
where you want the locale code to go.
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.
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.
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.
Examples:
licenses_group_url = file:///path/to/my/local/json-list-of-licenses.json
licenses_group_url = http://licenses.opendefinition.org/licenses/groups/od.json
Example:
smtp.server = smtp.gmail.com:587
Default value: None
The SMTP server to connect to when sending emails with optional port.
Example:
smtp.starttls = True
Default value: None
Whether or not to use STARTTLS when connecting to the SMTP server.
Example:
smtp.user = your_username@gmail.com
Default value: None
The username used to authenticate with the SMTP server.
Example:
smtp.password = yourpass
Default value: None
The password used to authenticate with the SMTP server.
Example:
smtp.mail_from = you@yourdomain.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.
Example:
email_to = you@yourdomain.com
Default value: None
This controls where the error messages will be sent to.
Example:
error_email_from = paste@localhost
Default value: None
This controls from which email the error messages will come from.