There are times when the popular commenting service Disqus is not a good fit. We recently launched GDPR Busters, a site dedicated to busting GDPR myths and helping organizations with compliance. This site is powered by the Ghost blogging software, which has no built-in commenting system, so we needed to setup our own. Being a website about GDPR, we wanted to follow the principle of data minimization, which is why we needed a commenting system that allows anonymous posting and which doesn't require to be hosted by a third party.


While we wrote our own self-hosted commenting system in the past, Juvia. we no longer maintain it actively. We do not want to take on the burden of maintaining the commenting system's codebase. Our search for an open source commenting system that can be integrated into Ghost eventually led us to Isso, which is written in Python.

In this article I'll show you how to install Isso on an Ubuntu server, how to integrate it into Nginx through reverse proxy, and how to integrate it into any website.

1 Installing Isso

The recommended way to install Isso is through pip, the Python package manager. Ubuntu also provides a package through APT, but unfortunately it is broken.

It is also recommended that you make use of virtualenv, a tool for managing isolated Python environments.

I actually think that something like virtualenv shouldn't be necessary. But alas, the way the Python package management system works makes it so that using virtualenv is a good idea.

Start by installing pip, virtualenv, and a compiler:

$ sudo apt install build-essential python-dev python-pip virtualenv

Next, create a virtualenv directory in /opt/isso:

$ sudo virtualenv /opt/isso

Then open a root shell and activate the created virtualenv:

$ sudo -H bash
# source /opt/isso/bin/activate

Inside that root shell with virtualenv enabled, install Isso and GUnicorn:

(isso:virtualenv)# pip install isso
(isso:virtualenv)# pip install gunicorn

Finally, exit the root shell:

# exit

2 Creating a user

We want Isso to run as a separate, unprivileged user so that any problems or vulnerabilities there do not fully escalate to the rest of the system. Create a user account:

$ sudo adduser isso

3 Creating data directories

Isso stores its comments in a database file, and it logs activity to a log file. So let's create directories for storing those files:

$ sudo mkdir /var/lib/isso
$ sudo mkdir /var/log/isso

We also make sure that those directories are owned by user 'isso':

$ sudo chown isso:isso /var/lib/isso
$ sudo chown isso:isso /var/log/isso

4 Configuring Isso

We configure Isso with a configuration file. Create /etc/isso.cfg with this content:

name = comments

; database location, check permissions, automatically created if not exists
dbpath = /var/lib/isso/comments.db

; Your website or blog address (not the location of Isso!)
; You can add multiple hosts for local development
; or SSL connections. There is no wildcard to allow
; any domain.
host =

;To moderate comments, either use the activation or deletion URL in the logs
;or use SMTP to get notified on new comments including the URLs
;for activation and deletion:
;notify = smtp

enabled = false
purge-after = 30d

host = localhost
port = 25
security = none
from =
timeout = 10

; Enable basic spam protection features, e.g. rate-limit per IP address
; (/24 for IPv4, /48 for IPv6).
enabled = true
ratelimit = 2
direct-reply = 3
reply-to-self = false

options = strikethrough, superscript, autolink
allowed-elements =
allowed-attributes =

The main items to customize are:

  • name -- pick a name for your Isso installation. This name will be used as the prefix in the Isso API URI. In the above example, Isso API endpoints will be made available under /comments.
  • dbpath -- filename of Isso's database file.
  • host -- the URL to your website. This is not the URL to the Isso API endpoint.
  • The [smtp] section. This configures how Isso should send emails. On many servers, an email server (e.g. Postfix) is already running on localhost port 25, but if you're using an external email server then be sure to point to that instead.

See the Isso server configuration reference for more information.

Ensure that this file is owned by root:

$ sudo chown root: /etc/isso.cfg
$ sudo chmod 644 /etc/isso.cfg

5 Create a systemd service

We want the OS to manage Isso: to boot it during system boot, to restart it when it crashes, etc. So we register a systemd service.

First, we need to create a boot script. Create a file /opt/isso/

set -e
source /opt/isso/bin/activate
export LANG=C.UTF-8
export ISSO_SETTINGS=/etc/isso.cfg
exec gunicorn -n gunicorn-isso -b --preload -w 4 --log-file /var/log/isso/isso.log isso.dispatch 2>>/var/log/isso/isso.log

This script starts Isso on port 1927 using GUnicorn. It also spawns 4 worker processes. If you want Isso to listen on a different port, or if you want more worker processes (for more concurrency) then be sure to change these parameters.

Make sure the script is owned by root and is executable:

$ sudo chown root: /opt/isso/
$ sudo chmod 755 /opt/isso/

Next, create a systemd service file /lib/systemd/system/isso.service:

Description=isso commenting system




# ensures that the service process and all its children can never gain new
# privileges.


Give the file the proper permissions:

$ sudo chown root: /lib/systemd/system/isso.service
$ sudo chmod 644 /lib/systemd/system/isso.service

Finally, start and enable the Isso service:

$ sudo systemctl daemon-reload
$ sudo systemctl enable isso
$ sudo systemctl start isso

6 Configure Nginx reverse proxy

Edit your website's virtual host configuration and make sure that you reverse proxy /comments (or whatever you configured in Isso's name option) to Isso's port (in this example,

location /comments {
    proxy_http_version 1.1;
    proxy_redirect default;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Server $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

Then restart Nginx.

7 Insert Isso into website

Now that Isso is up and running, the last remaining thing to do is to insert Isso into your site. Insert this snippet in the place where you want to display the comment box:

<section id="isso-thread"></section>

Then just before </body>, include the Isso Javascript:

<script data-isso="/comments" src="/comments/js/embed.min.js"></script>

(See Isso's client configuration reference for more options.)

Et voilà, a commenting section:

Just a preview, not a real commenting section

Enjoy Isso!