start writing docs properly, not in the README

1 files changed, 66 insertions, 0 deletions

diff --git a/doc/administration/configuration.rst b/doc/administration/configuration.rst
new file mode 100644
index 0000000..48afde1
--- /dev/null
+++ b/doc/administration/configuration.rst
@@ -0,0 +1,66 @@
+Configuration
+=============
+
+The main configuration of Fietsboek is done via ``.ini``-files. By default,
+three such files exist:
+
+* ``production.ini`` contains the configuration for the production environment.
+  It turns off debugging features (as they are a security risk!) and should
+  contain the URL of the production database. This is the main file you want to
+  use if you just want to deploy Fietsboek.
+* ``development.ini`` contains the configuration for local development on
+  Fietsboek. **This should not be used for production purposes, as it provides
+  debugging information that poses a security risk!**
+* ``testing.ini`` contains the configuration that the automated tests will use.
+
+Most of the configuration is in the ``[app:main]`` category and looks like this:
+
+.. code:: ini
+
+    [app:main]
+    use = egg:fietsboek
+
+    pyramid.reload_templates = false
+    pyramid.debug_authorization = false
+    pyramid.debug_notfound = false
+    pyramid.debug_routematch = false
+    pyramid.default_locale_name = en
+
+    email.from = fietsboek@kingdread.de
+    email.smtp_url = debug://localhost:1025
+
+    available_locales = en de
+    enable_account_registration = true
+
+    session_key = <EDIT THIS>
+
+    sqlalchemy.url = sqlite:///%(here)s/fietsboek.sqlite
+
+    retry.attempts = 3
+
+* You should leave the ``use``, ``pyramid.reload_templates`` and
+  ``pyramid.debug_*`` settings as they are.
+* ``pyramid.default_locale_name`` can be used to set the default language of
+  the installation. Note that Fietsboek will try to detect the user's language,
+  so the ``default_locale_name`` is used as a fallback.
+* ``available_locales`` sets the list of available languages. Currently,
+  Fietsboek ships with English ("en") and German ("de"). Removing a language
+  from this list will make it unavailable. If you create a custom language
+  locally, make sure to add it to this list here!
+* ``enable_account_registration`` can be used to enable and disable the
+  creation of new accounts via the web interface, for example if you want to
+  have a private instance. New accounts can always be created using the CLI
+  management tool.
+* ``email.from`` sets the sender of emails, for example for account verifications.
+* ``email.smtp_url`` sets the URL of the SMTP server. The following formats are accepted:
+
+  * ``debug://`` a debug implementation that simply prints emails to the
+    standard output. Should not be used in production, as no emails would ever
+    arrive.
+  * ``smtp://host:port`` use the given SMTP server (without transport encryption!)
+  * ``smtp+ssl://host:port`` use the given SMTP server over a SSL connection
+  * ``smtp+starttls://host:port`` use the given SMTP server and the STARTTLS
+    command to start an encrypted channel.
+
+* ``email.username`` and ``email.password`` can be used to set the login
+  information for the SMTP server.