Configuration Guide

In the following, <VENV_DIR> refers to the python virtual environment where you installed Kansha.

nagare-admin reference


Configuration file

Beware! The configuration file format changed since Kansha 2.0.0. If you are upgrading from a 1.0.X version, you have to convert manually your configuration file to the new format below.

Kansha features can be activated and customized with a configuration file like this:

path = app kansha
name = kansha
debug = off
redirect_after_post = on
as_root = on
title = <<APP_TITLE>> # should be short!
banner = <<LONG_TITLE>> # or motto/slogan or empty
favicon = # path (optional)
activity_monitor = <<MONITOR_EMAIL>> # optional
crypto_key = <<PASSPHRASE>> # MANDATORY!!!!
disclaimer = # message to display on login screens, below the forms (optional)

debug = off
activated = on
uri = postgres://<<DBUSER>>:<<DBPASS>>@<<DBHOST>>:<<DBPORT>>/<<DBNAME>> # adapt to your own DBMS
metadata = elixir:metadata
populate = kansha.populate:populate
# especially useful for mysql
#pool_recycle = 3600

engine = sqlite
collection = kansha
index_folder = <<DATA_DIR>>

# built in authentication system
activated = <<AUTH_DB>>
# moderator email if needed
moderator = <<MOD_EMAIL>> # or empty
# automatically create an identicon for new users (on|off)
identicons = on
# default values to fill in the login form (useful for a demo board)
default_username = <<DEFAULT_USERNAME>>
default_password = <<DEFAULT_PASSWORD>>

# authenticate with LDAP
activated = <<AUTH_LDAP>>
users_base_dn = <<AUTH_LDAP_USERS_BASE_DN>>
schema = <<AUTH_LDAP_CLASS>>

# authenticate with third party apps
activated = <<AUTH_OAUTH>>

# as many oauth providers as you wish
activated = <<AUTH_OAUTH>>
key = <<AUTH_OAUTH_KEY>>
secret = <<AUTH_OAUTH_SECRET>>

major = fr
minor = FR

activated = on
host = <<MAIL_HOST>>
port = <<MAIL_PORT>>
default_sender = <<MAIL_SENDER>>

basedir = <<DATA_DIR>>/assets
baseurl = /kansha/services
max_size = 20480



args="('<<DATA_DIR>>/logs/<<LOG_FILE>>', 'a', 10485760, 8, 'UTF-8')"

Just replace the <<PLACEHOLDERS>> with your actual values.

For your convenience, you can generate a configuration template into your current directory:

$ <VENV_DIR>/bin/kansha-admin save-config

The template is kansha.cfg. Edit it as you need. Ensure the folders you set for logs, assets… do exist.

To manage and run Kansha with your own custom configuration:

$ <VENV_DIR>/bin/nagare-admin create-db /path/to/your/kansha.cfg
$ <VENV_DIR>/bin/kansha-admin alembic-stamp head /path/to/your/kansha.cfg
$ <VENV_DIR>/bin/kansha-admin create-index /path/to/your/kansha.cfg
$ <VENV_DIR>/bin/nagare-admin serve /path/to/your/kansha.cfg

The different sections are detailled below.


Here you configure the base application.

Reference to the root component factory of the application (don’t edit!).
URL prefix of the application (/name/…).
If on, the application is also available without URL prefix, directly as root URL.
If on, display the web debug page when an exception occurs. The nagare[debug] extra must be installed. Never activate on a production site!
If on, every POST is followed by a GET thanks to a redirect. That way, visitors can safely use the back button on their browsers.
Short name for your instance, displayed in various places of the interface. It is the identity of your site. Keep it short (less than 10 chars).
Longer title for your site, kind of motto or slogan. It is displayed below the logo on the login page.
Name of the theme you want to use, a default one is bundled with Kansha and is named “kansha_flat”.
Path to a favicon file that will be applied to your site.
Email address or nothing. If an email address is provided, activity reports will be sent to it regularly. See Periodic tasks.
Required: this key is used to encrypt cookies. You must change it to secure your site. Put in an hundred random chars (ask a typing monkey).
This message is displayed below the login form. You can leave it empty of course.


Kansha data are stored in an SQL database. Thanks to SQLAlchemy, we support all the major databases of the market.

Depending on the DBMS you use, you may need to create the target database first.

Configuration options:

SQL Alchemy URI. See
If you are using MySQL as your database backend, you may need to set this option if the mysql configuration sets an automatic disconnection.

Let the other options at their default values.

Note for Postgresql (recommended DBMS for production sites) users:

  • install the needed dependencies:

    $ <VENV_DIR>/bin/easy_install kansha[postgres]

Note for MySQL users:

  • install the needed dependencies:

    $ <VENV_DIR>/bin/easy_install kansha[mysql]

Note for SQLite users: SQLite is not recommmended for production environments as it does not support schema migrations. If you use SQLite, you won’t be able to migrate your data when you install a new version of Kansha.


You can use up to four different systems, as modules, to authenticate your users in Kansha. You can activate as many modules as you want (at least one).

Module dbauth

Database authentication. Users must register first via the web interface.

Configuration options:

Whether to activate this module.
Whether a unique avatar should be created for each new user instead of the default anonymous one (on / off). Default is on.
If present, must be an email address. This activates moderation and all registration requests are fowarded to the moderator for approval. Otherwise, registration is free for humans. A CAPTCHA prevents robots from submitting.

Module ldapauth

Use this module to authenticate your users against an LDAP or Active Directory database.

You will need to install some additional packages:

$ <VENV_DIR>/bin/easy_install kansha[ldap]

Configuration options:

Activate only if you have some LDAP Directory.
name or address of the LDAP server.
(optional) port to connect to.
The base DN your users are under.

The driver to use depending on your schema:

  • kansha.authentication.ldap.ldap_auth:NngLDAPAuth for InetOrgPerson
  • kansha.authentication.ldap.ldap_auth:ADLDAPAuth for Active Directory

Note: the kansha.authentication.ldap.ldap_auth:NngLDAPAuth driver expects the fields “displayName” and “mail” to be set.

Module oauth

This governs the OAuth based authentication system. You need to activate it if you wish to let your users connect with their accounts on third party sites or applications.

For that, you configure a provider as a subsection of oauth.

The name of the subsection is the provider name (list below) in lowercase. Each subsection has the following configuration parameters:

on or off.
Write here the API key of the service you intend to use (you have to register with the service first to get one)
Write here the secret that authenticates your site by the service you intend to use (you have to register with the service first to get one)

The availble providers are:

  • Google,
  • Twitter,
  • Facebook,
  • Github.


activated = on

activated = on
key =

activated = on
key = 0000000000000000000

Send Mail

All notifications are sent by mail, so you’d better configure an outgoing SMTP server.

SMTP server to use.
The port the server listens on.
The sender address that will appear on all the messages sent by your site.

Asset Manager

You can attach files and images to cards, so you need to set where they will be stored on disk.

The folder where to store uploaded files.
The maximum allowed size of uploaded files, in kilobytes.


Default language for your site, two-letter ISO language code.
Default region for your site, two-letter ISO country code.


This is the configuration for the standard python logger. See for a complete explanation.

At a minimum, configure the path to the log file and the logging level.