rewrite CONFIGURATION.md in reST and extend document

docs/CONFIGURATION.md

@@ -1,90 +0,0 @@
-Isso Configuration
-==================
-
-The Isso configuration file is an INI-style textfile. You can point Isso to
-your configuration file either with `-c path/to/isso.cfg` or with a environment
-variable set to the *absolute* path.
-
-The configuration has several sections: *general* for general application behavior,
-*server* to specify host and port when not using uWSGI, *SMTP* to send mail
-notifications (heavily recommended to use) and *guard*, a naive solution for spam
-and abuse detection.
-
-## Example Configuration
-
-    [general]
-    dbpath = /var/lib/isso/comments.db
-    host = https://example.tld/
-    [server]
-    port = 1234
-
-For more information on the syntax, refer to [Wikipedia: INI file][1]
-
-[1]: https://en.wikipedia.org/wiki/INI_file
-
-## general
-
-dbpath
-: location to the SQLite3 database, defaults to /tmp/isso.db (may pruned
-after system restart, so use a proper location).
-
-secretkey
-: session key. If you restart the application several times per hour for
-whatever reason, use a static key. Defaults to a random string per application
-start.
-
-host
-: location to your website or blog. When you start Isso, it will try to
-establish a connection to your website (a simple HEAD request). If this
-check fails, none can comment on your website.
-
-max-age
-: time to allow users to remove or edit their comments. Defaults to `15m`.
-
-## server (not applicable for uWSGI)
-
-host
-: interface to listen on, defaults to `localhost`.
-
-port
-: port to listen on, defaults to 8080.
-
-reload
-: reload application, when editing the source code (only useful for developers),
-disabled by default.
-
-## moderation
-
-enabled
-: enable comment moderation queue, disabled by default
-
-purge-after
-: remove unprocessed comments in moderation queue after, by default, `30d`.
-
-## SMTP
-
-username
-: self-explanatory
-
-password
-: self-explanatory (yes, plain text, create a dedicated account for notifications.
-
-host
-: server host, defaults to `localhost`.
-
-port
-: server port, defaults to `465`.
-
-ssl
-: use SSL, defaults to `on`.
-
-to
-: recipient address
-
-from
-: sender address
-
-## guard
-
-enabled
-: defaults to `on`.

docs/CONFIGURATION.rst

@@ -0,0 +1,177 @@
+Isso Configuration
+==================
+
+The Isso configuration file is an `INI-style`__ textfile.  Below is an example for
+a basic Isso configuration. Each section has its own documentation.
+
+.. code-block:: ini
+
+    [general]
+    dbpath = /var/lib/isso/comments.db
+    host = https://example.tld/
+    [server]
+    port = 1234
+
+You can point Isso to your configuration file either witg a command-line parameter
+or using an environment variable:
+
+.. code-block:: sh
+
+    ~> isso -c path/to/isso.cfg
+    ~> env ISSO_SETTINGS=path/to/isso.cfg isso
+
+__ https://en.wikipedia.org/wiki/INI_file
+
+
+General
+-------
+
+In this section, you configure most comment-related options such as database path,
+session key and hostname. Here are the default values for this section:
+
+.. code-block:: ini
+
+    [general]
+    dbpath = /tmp/isso.db
+    host = http://localhost:8080/
+    max-age = 15m
+    session-key = ... # python: binascii.b2a_hex(os.urandom(24))
+
+dbpath
+    file location to the SQLite3 database, highly recommended to change this
+    location to a non-temporary location!
+
+host
+    URL to your website. When you start Isso, it will probe your website with
+    a simple ``GET /`` request to see if it can reach the webserver. If this
+    fails, Isso may not be able check if a web page exists, thus fails to
+    accept new comments.
+
+session-key
+    private session key to validate client cookies. If you restart the
+    application several times per hour for whatever reason, use a fixed
+    key.
+
+max-age
+    time range that allows users to edit/remove their own comments. See
+    :ref:`Appendum: Timedelta <appendum-timedelta>` for valid values.
+
+
+Moderation
+----------
+
+Enable moderation queue and handling of comments still in moderation queue
+
+.. code-block:: ini
+
+    [moderation]
+    enabled = false
+    purge-after = 30d
+
+enabled
+    enable comment moderation queue. This option only affects new comments.
+    Comments in modertion queue are not visible to other users until you
+    activate them.
+
+purge-after
+    remove unprocessed comments in moderation queue after given time.
+
+
+Server
+------
+
+HTTP server configuration, does **not** apply to uWSGI.
+
+.. code-block:: ini
+
+    [server]
+    host = localhost
+    port = 8080
+    reload = off
+
+host
+    listen on specified interface
+
+port
+    application port
+
+reload
+    reload application, when the source code has changed. Useful for
+    development (don't forget to use a fixed `session-key`).
+
+
+SMTP
+----
+
+Isso can notify you on new comments via SMTP. In the email notification, you
+also can moderate comments. If the server connection fails during startup, a
+null mailer is used.
+
+.. code-block:: ini
+
+    [smtp]
+    username =
+    password =
+    host = localhost
+    port = 465
+    ssl = on
+    to =
+    from =
+
+username
+    self-explanatory, optional
+
+password
+    self-explanatory (yes, plain text, create a dedicated account for
+    notifications), optional.
+
+host
+    SMTP server
+
+port
+    SMTP port
+
+ssl
+    use SSL to connect to the server. Python probably does not validate the
+    certificate. Needs research, though. But you should use a dedicated
+    email account anyways.
+
+to
+    recipient address, e.g. your email address
+
+from
+    sender address, e.g. isso@example.tld
+
+
+Guard
+-----
+
+Enable basic spam protection features, e.g. rate-limit per IP address (``/24``
+for IPv4, ``/48`` for IPv6).
+
+.. code-block:: ini
+
+    [guard]
+    enabled = true
+    ratelimit = 2
+
+enabled
+    enable guard, recommended in production. Not useful for debugging
+    purposes.
+
+ratelimit: N
+    limit to N new comments per minute.
+
+
+Appendum
+---------
+
+.. _appendum-timedelta:
+
+Timedelta
+    A human-friendly representation of a time range: `1m` equals to 60
+    seconds. This works for years (y), weeks (w), days (d) and seconds (s),
+    e.g. `30s` equals 30 to seconds.
+
+    You can add different types: `1m30s` equals to 90 seconds, `3h45m12s`
+    equals to 3 hours, 45 minutes and 12 seconds (12512 seconds).

isso/__init__.py

@@ -86,7 +86,7 @@ class Isso(object):
 
         self.conf = conf
         self.db = db.SQLite3(conf.get('general', 'dbpath'), conf)
-        self.signer = URLSafeTimedSerializer(conf.get('general', 'secretkey'))
+        self.signer = URLSafeTimedSerializer(conf.get('general', 'session-key'))
         self.j2env = Environment(loader=FileSystemLoader(join(dirname(__file__), 'templates/')))
 
         super(Isso, self).__init__(conf)

isso/core.py

@@ -51,9 +51,8 @@ class Config:
 
     default = [
         "[general]",
-        "dbpath = /tmp/isso.db", "secretkey = %r" % binascii.b2a_hex(os.urandom(24)),
+        "dbpath = /tmp/isso.db", "session-key = %r" % binascii.b2a_hex(os.urandom(24)),
-        "host = http://localhost:8080/", "passphrase = p@$$w0rd",
+        "host = http://localhost:8080/", "max-age = 15m",
-        "max-age = 15m",
         "[moderation]",
         "enabled = false",
         "purge-after = 30d",
@@ -64,7 +63,7 @@ class Config:
         "host = localhost", "port = 465", "ssl = on",
         "to = ", "from = ",
         "[guard]",
-        "enabled = on",
+        "enabled = true",
         "ratelimit = 2"
         ""
     ]

isso/db/spam.py

@@ -21,7 +21,7 @@ def check(func):
             'SELECT id FROM comments WHERE remote_addr = ? AND created > ?;'
         ], (c["remote_addr"], time.time() + 60)).fetchall()
 
-        if len(rv) >= 2:
+        if len(rv) >= self.db.conf.getint("guard", "ratelimit"):
             raise TooManyComments
 
         # block more than three comments as direct response to the post