--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/configuration.rst	Sun Jul 21 22:14:30 2019 +0200
@@ -0,0 +1,150 @@
+=============
+Configuration
+=============
+
+Salut à Toi main configuration is set in a file named ``sat.conf`` (which may be prefixed
+by a ``.`` if you want to hide it on suitable platforms). It is a common file used both by
+backend and all frontends (and even related project like SàT Pubsub).
+
+This file can located in the following paths (in order of parsing):
+  - ``/etc``
+  - ``~`` (``$HOME`` or your home directory)
+  - the directory where you are launching the backend or frontend from
+  - XDG directory for configuration (most of time it is
+    ``~/.config/sat/sat.conf``)
+
+If several configurations files are found, they are merged. In case of conflict, the
+option parsed last is the one used (in other words: if you have an option set in
+``/etc/sat.conf`` and the same one set in ``~/.sat.conf``, the one from ``~/.sat.conf``
+will be used because it is parsed after ``/etc``).
+
+Format
+======
+
+``sat.conf`` is a using the `INI`_ file format as understood by Python's
+`SafeConfigParser`_ (meaning that you can use interpolation).
+
+The ``DEFAULT`` section is used for global options, this is where you specify where are
+your media.
+
+Each frontend can have specific section with its name in lowercase (sections are case
+sensitive), and some backend plugin can use specific sections too (usually named ``plugin
+<plugin name>``). The ``pubsub`` section is used by ``SàT PubSub``. A section can also
+have the name of a web site used with Libervia web framework.
+
+
+To recapitulate, you can have the following sections in your ``sat.conf``:
+
+``[DEFAULT]``
+  the main, global section
+frontend name (in lower case)
+  frontend specific settings. Some examples:
+
+  - ``[cagou]``
+  - ``[jp]``
+  - ``[primitivus]``
+  - ``[libervia]``
+``[plugin <plugin name>]``
+  backend plugin specific settings. Some examples:
+
+  - ``[plugin account]``
+  - ``[plugin muc]``
+  - ``[plugin search]``
+``[pubsub]``
+  SàT PubSub settings
+``[<website name>]``
+  the settings of a website for Libervia web framework
+
+.. _INI: https://en.wikipedia.org/wiki/INI_file
+.. _SafeConfigParser: https://docs.python.org/2/library/configparser.html
+
+In the section, the option names suffixes are used to identify the type of settings:
+
+- ``_dir`` is used to indicate a path to a directory
+- ``_path`` is used to indicate a path (generally to a file, ``_dir`` being used for
+  directories)
+- ``_int`` indicate a integer
+- ``_list`` indicate a list comma-separated values
+- ``_dict`` indicate a dictionary
+- ``_json`` is used for complex data, represented with JSON format
+
+Remember that if you want to span your data on several lines (which is often used with
+``*_dict`` or ``*_json`` options), you need to indent the extra lines and keep the same
+indentation.
+
+Sample
+======
+
+Here is a configuration that you can use as a model to specify your own settings. Check
+the comments to get the meaning of each option.
+
+.. sourcecode:: cfg
+
+    [DEFAULT]
+    ; where SàT media are located
+    media_dir = ~/workspace/sat_media
+    log_level = debug
+    ; domain used for new accounts
+    xmpp_domain = example.net
+    ; list of profiles with admin rights
+    admins_list = toto,titi
+    ; settings to let the backend send emails
+    email_from = NOREPLY@example.net
+    email_server = localhost
+    # email_port =
+    # email_username =
+    # email_password =
+    # email_starttls = true
+    # email_auth = true
+    # email_admins_list = toto@example.net, titi@example.org
+    ; override DNS records
+    hosts_dict = {
+        "example.org": {"host": "127.0.0.1"}
+        }
+
+    [plugin account]
+    ; where a new account must be created
+    new_account_server = localhost
+    new_account_domain = example.net
+
+    [plugin muc]
+    ; default room to use in the "Join room" menu
+    default_muc = sat@chat.jabberfr.org
+
+    [primitivus]
+    log_level = debug
+    ; how the logs are formatted
+    ; note that "%" must be doubled here
+    log_fmt = %%(levelname)s: %%(message)s
+    ; use bracketed paste mode
+    bracketed_paste = true
+
+    [jp]
+    ; how to use xdotool to refresh Firefox when doing "jp blog edit"
+    blog_preview_open_cmd = firefox -new-tab {url}
+    blog_preview_update_cmd = /bin/sh -c "WID=$(xdotool search --name 'Mozilla Firefox' | head -1); xdotool windowactivate $WID; xdotool key F5"
+    ; and below the equivalent with Konqueror
+    # blog_preview_open_cmd = konqueror {url}
+    # blog_preview_update_cmd = /bin/sh -c "qdbus $(qdbus org.kde.konqueror\*) /konqueror/MainWindow_1 reload"
+
+    [libervia]
+    ; do we want "http", "https" or "both"?
+    connection_type = both
+    port = 8080
+    port_https = 8443
+    ; external port used for HTTPS (0 to use "port_https" value)
+    port_https_ext = 443
+    ; TLS public certificate or private key
+    ; and public certificate combined (PEM format)
+    tls_certificate = libervia.pem
+    ; TLS certificate private key (PEM format)
+    tls_private_key
+    ; if true (or 1), HTTP will redirect to HTTPS
+    redirect_to_https = 1
+    ; passphrase for libervia profile
+    passphrase = something_secure
+    ; here we redirect main libervia page
+    ; to the blog of a profile named "some_profile"
+    url_redirections_dict = {
+      "/": "/u/some_profile"
+      }