arno/isso
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

rewrite CONFIGURATION.md in reST and extend document

Browse Source
This commit is contained in:
Martin Zimmermann 2013-10-27 12:44:59 +01:00
parent 2db98d0d34
commit 94b1fef28e
5 changed files with 182 additions and 96 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

90
docs/CONFIGURATION.md
View File

@ -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`.

177
docs/CONFIGURATION.rst Normal file
View File

@ -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).

2
isso/__init__.py
View File

@ -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)

7
isso/core.py
View File

@ -51,9 +51,8 @@ class Config:
default = [
"[general]",
"dbpath = /tmp/isso.db", "secretkey = %r" % binascii.b2a_hex(os.urandom(24)),
"host = http://localhost:8080/", "passphrase = p@$$w0rd",
"max-age = 15m",
"dbpath = /tmp/isso.db", "session-key = %r" % binascii.b2a_hex(os.urandom(24)),
"host = http://localhost:8080/", "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"
""
]

2
isso/db/spam.py
View File

@ -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