Skip to main content

Getting Isso to work on CentOS 6 and nginx

Isso is an open source alternative to Disqus. Users can post anonymous comments and everything is stored in an SQLite database on your server.

The server is written in Python and the client is pure JavaScript.

Warning: this post explains how I got Isso to work on my server, this is not aimed to be a reference guide! There probably are some installation procedures to improve and maybe some bugs to report.


They provide prebuilt packages for most GNU/Linux distributions but, unfortunately, not for CentOS (which is powering my VPS). So I had to install Isso with pip.

First install virtualenv, Python development headers, SQLite and C compiler with yum:

# yum install python-setuptools python-virtualenv python-devel sqlite
# yum groupinstall "Development tools"

Then create a new directory in /opt and chown it to your user and group:

# mkdir /opt/isso
# chown <user>:<group> /opt/isso

Activate virtualenv as regular user:

$ virtualenv /opt/isso
$ source /opt/isso/bin/activate

We can now install Isso with pip:

$ pip install isso


Note that I encountered some problems while installing the isso package.

First, the libffi package was not found by misaka (an isso dependency), I had to install libffi-devel:

# yum install libffi-devel

Then, the current version of the misaka package needed by isso wouldn't build, so I had to force the installation of a previous version. This will probably soon be fixed, but just in case, this is what I did:

$ pip install misaka==1.0.2

I also had to install argparse:

$ pip install argparse

And finally, this exception appeared when running the server:

Exception happened during processing of request from ('', 55431)
Traceback (most recent call last):
  File "/usr/lib64/python2.6/", line 570, in process_request_thread
    self.finish_request(request, client_address)
  File "/usr/lib64/python2.6/", line 332, in finish_request
    self.RequestHandlerClass(request, client_address, self)
  File "/usr/lib64/python2.6/", line 627, in __init__
  File "/opt/isso/lib/python2.6/site-packages/werkzeug/", line 217, in handle
    rv = BaseHTTPRequestHandler.handle(self)
  File "/usr/lib64/python2.6/", line 329, in handle
  File "/opt/isso/lib/python2.6/site-packages/werkzeug/", line 252, in handle_one_request
    return self.run_wsgi()
  File "/opt/isso/lib/python2.6/site-packages/werkzeug/", line 201, in run_wsgi
    traceback = get_current_traceback(ignore_system_exceptions=True)
  File "/opt/isso/lib/python2.6/site-packages/werkzeug/debug/", line 184, in get_current_traceback
    tb = Traceback(exc_type, exc_value, tb)
  File "/opt/isso/lib/python2.6/site-packages/werkzeug/debug/", line 235, in __init__
    self.frames.append(Frame(exc_type, exc_value, tb))
  File "/opt/isso/lib/python2.6/site-packages/werkzeug/debug/", line 402, in __init__
    self.filename = to_unicode(fn, get_filesystem_encoding())
  File "/opt/isso/lib/python2.6/site-packages/werkzeug/", line 62, in get_filesystem_encoding
    'filesystem encoding instead of {!r}'.format(rv),
ValueError: zero length field name in format

I just removed the line 62 in /opt/isso/lib/python2.6/site-packages/werkzeug/ Dirty as hell, but hey, it's working.


Let's create a configuration file for Isso in, for example, /opt/isso/etc/isso.cfg with the following:

; database location, check permissions, automatically created if not exists
dbpath = /opt/isso/comments.db
; your website or blog (not the location of Isso!)
host =

listen = http://localhost:8080/

You can launch Isso with:

$ isso -c /opt/isso/etc/isso.cfg run

The last thing we need to do is to configure nginx as a proxy to the Isso server.

The official documentation suggests that you use comments.example.tld as server name. I prefer www.example.tld/comments as it doesn't need another certificate when using HTTPS.

Add a location block in your nginx config and tell nginx to pass requests beginning with /comments to the local Isso server:

server {

    listen          443 ssl spdy;
    listen          [::]:443 ssl spdy;

    ssl_certificate /path/to/chained.pem;
    ssl_certificate_key /path/to/domain.key;

    root            /usr/share/nginx/html/www;

    location /comments {
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Script-Name /comments;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_pass http://localhost:8080;

We're done! We can now tweak the configuration file to activate moderation queue, email notifications, etc.