In the following, <VENV_DIR> refers to the python virtual environment where you installed Kansha.
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:
[application] 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 theme = <<CUSTOM_THEME_NAME>> favicon = # path (optional) activity_monitor = <<MONITOR_EMAIL>> # optional crypto_key = <<PASSPHRASE>> # MANDATORY!!!! disclaimer = # message to display on login screens, below the forms (optional) [database] 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 [search] engine = sqlite collection = kansha index_folder = <<DATA_DIR>> [authentication] # built in authentication system [[dblogin]] 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 [[ldaplogin]] activated = <<AUTH_LDAP>> host = <<AUTH_LDAP_SERVER>> users_base_dn = <<AUTH_LDAP_USERS_BASE_DN>> schema = <<AUTH_LDAP_CLASS>> # authenticate with third party apps [[oauthlogin]] activated = <<AUTH_OAUTH>> # as many oauth providers as you wish [[[<<PROVIDER>>]]] activated = <<AUTH_OAUTH>> key = <<AUTH_OAUTH_KEY>> secret = <<AUTH_OAUTH_SECRET>> [locale] major = fr minor = FR [services] [[mail_sender]] activated = on host = <<MAIL_HOST>> port = <<MAIL_PORT>> default_sender = <<MAIL_SENDER>> [[assets_manager]] basedir = <<DATA_DIR>>/assets baseurl = /kansha/services max_size = 20480 [logging] [[logger]] level=INFO [[handler]] class=logging.handlers.RotatingFileHandler 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 (
on, the application is also available without URL prefix, directly as root URL.
on, display the web debug page when an exception occurs. The
nagare[debug]extra must be installed. Never activate on a production site!
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.
- SQL Alchemy URI. See http://docs.sqlalchemy.org/en/rel_0_9/core/engines.html#supported-databases
- 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 choose one out of two search backends for the moment: SQLite or ElasticSearch. They both work independently from the database you chose to store your data in.
The SQLite backend is quite fast and capable but is only able to do prefix searches. More demanding sites may require ElasticSearch, or you may already have a running cluster on your network.
This backend is based upon SQLite FTS tables. You need sqlite 3.8.0 or newer. Yet, the search engine can still work with limited functionality down to sqlite 3.7.7. As far as Kansha is concerned, it should not make any difference, since it doesn’t use the missing features (for the moment).
- The base name of the index file (will be created).
- Where to put the index file (must exist).
Requires ElasticSearch v2.3.0 or above.
You need to install the python driver first:
$ <VENV_DIR>/bin/easy_install kansha[elastic]
- the name of the index on the ElasticSearch cluster (will be created).
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).
Database authentication. Users must register first via the web interface.
- Whether to activate this module.
- Whether a unique avatar should be created for each new user instead of the default anonymous one (
off). Default is
- 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.
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]
- 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:ADLDAPAuthfor Active Directory
kansha.authentication.ldap.ldap_auth:NngLDAPAuth driver expects the fields “displayName” and “mail” to be set.
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
The name of the subsection is the provider name (list below) in lowercase. Each subsection has the following configuration parameters:
- 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:
[[oauthlogin]] activated = on [[[google]]] activated = on key = xxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com secret = XXXXXXXXXXXXXXXXXXXXXXXX [[[facebook]]] activated = on key = 0000000000000000000 secret = XXXXXXXXXXXXXXXXXXXXXXXX
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.
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 https://docs.python.org/2/library/logging.config.html#configuration-file-format for a complete explanation.
At a minimum, configure the path to the log file and the logging level.