doc/configuration.rst
.. _configuration_guide:
Configuration Guide
===================
In the following, <VENV_DIR> refers to the python virtual environment where you installed Kansha.
``nagare-admin`` reference
--------------------------
Read http://www.nagare.org/trac/wiki/NagareAdmin.
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:
.. code-block:: INI
[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.
.. _application:
Application
-----------
Here you configure the base application.
path
Reference to the root component factory of the application (don't edit!).
name
URL prefix of the application (``/name/…``).
as_root
If ``on``, the application is also available without URL prefix, directly as root URL.
debug
If ``on``, display the web debug page when an exception occurs. The ``nagare[debug]`` extra must be installed. Never activate on a production site!
redirect_after_post
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.
title
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).
banner
Longer title for your site, kind of motto or slogan. It is displayed below the logo on the login page.
theme
Name of the theme you want to use, a default one is bundled with Kansha and is named "kansha_flat".
favicon
Path to a favicon file that will be applied to your site.
activity_monitor
Email address or nothing. If an email address is provided, activity reports will be sent to it regularly. See :ref:`periodic_tasks`.
crypto_key
**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).
disclaimer
This message is displayed below the login form. You can leave it empty of course.
Database
--------
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:
uri
SQL Alchemy URI. See http://docs.sqlalchemy.org/en/rel_0_9/core/engines.html#supported-databases
pool_recycle
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.
Search
------
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.
SQLite backend
^^^^^^^^^^^^^^
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).
Configuration options:
engine
sqlite
index
The base name of the index file (will be created).
index_folder
Where to put the index file (must exist).
ElasticSearch backend
^^^^^^^^^^^^^^^^^^^^^
Requires ElasticSearch v2.3.0 or above.
You need to install the python driver first::
$ <VENV_DIR>/bin/easy_install kansha[elastic]
Configuration options:
engine
elastic
index
the name of the index on the ElasticSearch cluster (will be created).
host
Optional
port
Optional
Authentication
--------------
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:
activated
Whether to activate this module.
identicons
Whether a unique avatar should be created for each new user instead of the default anonymous one (``on`` / ``off``). Default is ``on``.
moderator
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:
activated
Activate only if you have some LDAP Directory.
host
name or address of the LDAP server.
port
(optional) port to connect to.
users_base_dn
The base DN your users are under.
schema
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:
activated
``on`` or ``off``.
key
Write here the API key of the service you intend to use (you have to register with the service first to get one)
secret
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.
..
* Dropbox,
* Salesforce,
* Flickr,
* Vimeo,
* Bitbucket,
* Yahoo,
* Dailymotion,
* Viadeo,
* Linkedin,
* Foursquare,
* or Instagram.
Example:
.. code-block:: INI
[[oauthlogin]]
activated = on
[[[google]]]
activated = on
key = xxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com
secret = XXXXXXXXXXXXXXXXXXXXXXXX
[[[facebook]]]
activated = on
key = 0000000000000000000
secret = XXXXXXXXXXXXXXXXXXXXXXXX
.. _mail:
Send Mail
---------
All notifications are sent by mail, so you'd better configure an outgoing SMTP server.
host
SMTP server to use.
port
The port the server listens on.
default_sender
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.
basedir
The folder where to store uploaded files.
max_size
The maximum allowed size of uploaded files, in kilobytes.
Locale
------
major
Default language for your site, two-letter ISO language code.
minor
Default region for your site, two-letter ISO country code.
Logging
-------
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.