Configuration

INI File

Kotti is configured using an INI configuration file. The Installation section explains how to get hold of a sample configuration file. The [app:kotti] section in it might look like this:

[app:kotti]
use = egg:Kotti
pyramid.reload_templates = true
pyramid.debug_authorization = false
pyramid.debug_notfound = false
pyramid.debug_routematch = false
pyramid.debug_templates = true
pyramid.default_locale_name = en
pyramid.includes = pyramid_debugtoolbar
                   pyramid_tm
mail.default_sender = yourname@yourhost
sqlalchemy.url = sqlite:///%(here)s/Kotti.db
kotti.site_title = Kotti
kotti.secret = changethis1

Various aspects of your site can be changed right here.

Overview of settings

This table provides an overview of available settings. All these settings must go into the [app:kotti] section of your Paste Deploy configuration file.

Only the settings in bold letters required. The rest has defaults.

Do take a look at the required settings (in bold) and adjust them in your site’s configuration. A few of the settings are less important, and sometimes only used by developers, not integrators.

Setting

Description

kotti.site_title

The title of your site

kotti.secret

Secret token used for the initial admin password

kotti.secret2

Secret token used for email password reset token

sqlalchemy.url

SQLAlchemy database URL

mail.default_sender

Sender address for outgoing email

kotti.asset_overrides

Override Kotti’s templates

kotti.authn_policy_factory

Component used for authentication

kotti.authz_policy_factory

Component used for authorization

kotti.available_types

List of active content types

kotti.base_includes

List of base Python configuration hooks

kotti.caching_policy_chooser

Component for choosing the cache header policy

kotti.configurators

List of advanced functions for config

kotti.date_format

Date format to use, default: medium

kotti.datetime_format

Datetime format to use, default: medium

kotti.depot_mountpoint

Configure the mountpoint for the blob storage. See Working with Blob Data in Kotti for details.

kotti.depot_replace_wsgi_file_wrapper

Replace you WSGI server’s file wrapper with pyramid.response.FileIter.

kotti.depot.*.*

Configure the blob storage. See Working with Blob Data in Kotti for details.

kotti.fanstatic.edit_needed

List of static resources used for edit interface

kotti.fanstatic.view_needed

List of static resources used for public interface

kotti.login_success_callback

Override Kotti’s default login_success_callback function

kotti.max_file_size

Max size for file uploads, default: 10 (MB)

kotti.modification_date_excludes

List of attributes in dotted name notation that should not trigger an update of modification_date on change

kotti.populators

List of functions to fill initial database

kotti.request_factory

Override Kotti’s default request factory

kotti.reset_password_callback

Override Kotti’s default reset_password_callback function

kotti.root_factory

Override Kotti’s default Pyramid root factory

kotti.sanitize_on_write

Configure Sanitizers to be used on write access to resource objects

kotti.sanitizers

Configure available Sanitizers

kotti.search_content

Override Kotti’s default search function

kotti.session_factory

Component used for sessions

kotti.templates.api

Override api object available in templates

kotti.time_format

Time format to use, default: medium

kotti.url_normalizer

Component used for url normalization

kotti.zcml_includes

List of packages to include the ZCML from

mail.host

Email host to send from

pyramid.default_locale_name

Set the user interface language, default en

pyramid.includes

List of Python configuration hooks

kotti.secret and kotti.secret2

The value of kotti.secret will define the initial password of the admin user. Thus, if you define kotti.secret = mysecret, the admin password will be mysecret. Log in and change the password at any time through the web interface.

The kotti.secret token is also used for signing browser session cookies. The kotti.secret2 token is used for signing the password reset token.

Here’s an example:

kotti.secret = myadminspassword
kotti.secret2 = $2a$12$VVpW/i1MA2wUUIUHwY6v8O

Note

Do not use these values in your site

Override templates (kotti.asset_overrides)

In your settings file, set kotti.asset_overrides to a list of asset specifications. This allows you to set up a directory in your package that will mirror Kotti’s own and that allows you to override Kotti’s templates on a case by case basis.

As an example, image that we wanted to override Kotti’s master layout template. Inside the Kotti source, the layout template is located at kotti/templates/view/master.pt. To override this, we would add a directory to our own package called kotti-overrides and therein put our own version of the template so that the full path to our own custom template is mypackage/kotti-overrides/templates/view/master.pt.

We can then register our kotti-overrides directory by use of the kotti.asset_overrides setting, like so:

kotti.asset_overrides = mypackage:kotti-overrides/

Use add-ons

Add-ons will usually include in their installation instructions which settings one should modify to activate them. Configuration settings that are used to activate add-ons are:

  • pyramid.includes

  • kotti.available_types

  • kotti.base_includes

  • kotti.configurators

pyramid.includes

pyramid.includes defines a list of hooks that will be called when your Kotti app starts up. This gives the opportunity to third party packages to add registrations to the Pyramid Configurator API in order to configure views and more.

Here’s an example. Let’s install the kotti_twitter extension and add a Twitter profile widget to the right column of all pages. First we install the package from PyPI:

bin/pip install kotti_twitter

Then we activate the add-on in our site by editing the pyramid.includes setting in the [app:kotti] section of our INI file (if a line with pyramid.includes does not exist, add it).

pyramid.includes = kotti_twitter.include_profile_widget

kotti_twitter also asks us to configure the Twitter widget itself, so we add some more lines right where we were:

kotti_twitter.profile_widget.user = dnouri
kotti_twitter.profile_widget.loop = true

The order in which the includes are listed matters. For example, when you add two slots on the right hand side, the order in which you list them in pyramid.includes will control the order in which they will appear. As an example, here’s a configuration with which the search widget will be displayed above the profile widget:

pyramid.includes =
    kotti_twitter.include_search_widget
    kotti_twitter.include_profile_widget

Read more about including packages using ‘pyramid.includes’ in the Pyramid documentation.

kotti.available_types

The kotti.available_types setting defines the list of content types available. The default configuration here is:

kotti.available_types = kotti.resources.Document kotti.resources.File

An example that removes File and adds two content types:

kotti.available_types =
    kotti.resources.Document
    kotti_calendar.resources.Calendar
    kotti_calendar.resources.Event

kotti.populators

The default configuration here is:

kotti.populators = kotti.populate.populate

Populators are functions with no arguments that get called on system startup. They may then make automatic changes to the database (before calling transaction.commit()).

kotti.search_content

Kotti provides a simple search over the content types based on kotti.resources.Content. The default configuration here is:

kotti.search_content = kotti.views.util.default_search_content

You can provide an own search function in an add-on and register this in your INI file. The return value of the search function is a list of dictionaries, each representing a search result:

[{'title': 'Title of search result 1',
  'description': 'Description of search result 1',
  'path': '/path/to/search-result-1'},
 {'title': 'Title of search result 2',
  'description': 'Description of search result 2',
  'path': '/path/to/search-result-2'},
 ...
 ]

An add-on that defines an alternative search function is kotti_solr, which provides an integration with the Solr search engine.

Configure the user interface language

By default, Kotti will display its user interface in English. The default configuration is:

pyramid.default_locale_name = en

You can configure Kotti to serve a German user interface by saying:

pyramid.default_locale_name = de_DE

The list of available languages is here.

Configure authentication and authorization

You can override the authentication and authorization policy that Kotti uses. By default, Kotti uses these factories:

kotti.authn_policy_factory = kotti.authtkt_factory
kotti.authz_policy_factory = kotti.acl_factory

These settings correspond to pyramid.authentication.AuthTktAuthenticationPolicy and pyramid.authorization.ACLAuthorizationPolicy being used.

Sessions

The kotti.session_factory configuration variable allows the overriding of the default session factory. By default, Kotti uses pyramid_beaker for sessions.

Caching

You can override Kotti’s default set of cache headers by changing the kotti.views.cache.caching_policies dictionary, which maps policies to headers. E.g. the Cache Resource entry there caches all static resources for 32 days. You can also choose which responses match to which caching policy by overriding Kotti’s default cache policy chooser through the use of the kotti.caching_policy_chooser configuration variable. The default is:

kotti.caching_policy_chooser = kotti.views.cache.default_caching_policy_chooser

URL normalization

Kotti normalizes document titles to URLs by replacing language specific characters like umlauts or accented characters with its ascii equivalents. You can change this default behaviour by setting kotti.url_normalizer.map_non_ascii_characters configuration variable to False. If you do, Kotti will leave national characters in URLs.

You may also replace default component used for url normalization by setting kotti.url_normalizer configuation variable.

The default configuration here is:

kotti.url_normalzier = kotti.url_normalizer.url_normalizer
kotti.url_normalizer.map_non_ascii_characters = True

Local navigation

Kotti provides a build in navigation widget, which is disabled by default. To enable the navigation widget add the following to the pyramid.includes setting:

pyramid.includes = kotti.views.slots.includeme_local_navigation

The add-on kotti_navigation provides also a navigation widget with more features. With this add-on included your configuration looks like:

pyramid.includes = kotti_navigation.include_navigation_widget

Check the documentation of kotti_navigation for more options.