Pythonity Blog Pythonity Blog

How To Use Isso on Your Site

In our previous post, we covered why Isso is the way to go if you want comments on your website. We were specifically talking about Pelican, but this solution can be applied to other static site generators like Jekyll, Octopress, etc. as well. And for that matter, not just static site generators - Isso is universal and only requires the addition of a couple lines of HTML, so you could use it practically anywhere you wish. Now, let's help you get it working on your server.

I'll just go out on a limb and assume that if you managed to get your site up on the internet (getting a server, a domain, directing the domain to the server, installing some kind of webserver and configuring it) and you're running some kind of CMS or static site generator, then you have some technical knowledge. Or you're really smart. Or lucky. Or you're good at following tutorials on some random blogs (did I just burn myself?). Either way, I have to assume something and not start with 'What to look for when buying your first computer'.

And just to make things clear from the beginning - I will also be using apt-get as my package manager (if you use a different one, chances are you already know what to do) and Python 3 (to do my - however small - part in making the new version more popular).

Python knowledge isn't required, so don't worry if you never used it. What you need, though, is to have it - and a couple of other things - installed:

$ sudo apt-get install python3 python3-pip sqlite3 build-essential

Also, I wouldn't be myself if I didn't recommend using virtualenv, but it's not really necessary and I don't want to add yet another thing to learn for those of you that never used it and/or don't know what it is. So if you do know what it is, feel free to use it like with any other Python project, and if you don't then either read up on it (definitely worth it if you're interested in Python) or ignore this paragraph. OK? OK.

Enough small talk - let's install the damn thing!

$ sudo pip3 install isso

Wait - is that it? Well, kinda. If the whole thing was a one-liner then a 'How to' article on it wouldn't probably be needed, don't you think? We installed it, but we still have to run it in the background and enable it on the website.

In addition to that, before running it we have to create a config file. All options (like email notifications, comment moderation, and more) are listed in Isso docs, so go ahead and read those - I'll just include the ones that are required:

dbpath = /opt/isso/comments.db
host =

listen = http://localhost:8001/

They're pretty self-explanatory, but this is a 'How To' after all, dammit! So:

  • dbpath - path to SQLite database file; make sure it's writable by the user that Isso is running as
  • host - URL of your website (or websites, via docs)
  • listen - interface to listen on, that we will then proxy via our webserver

OK, let's assume that our config file is ready and we saved it as /opt/isso/isso.conf. Awesome. Now let's take care of running the Isso app in the background.

There is more than one way to do it -- I prefer supervisor, but my boss for example hates doing things nice and easy, so he made me use init (not even systemd! ugh) on our company server. So it's more or less up to you (or your boss...) to pick the method of your choice, with some example config files already provided.

And since I actually do like things nice and easy, let's move forward with supervisor:

$ sudo apt-get install supervisor

We then need to add the config file (/etc/supervisor/conf.d/isso.conf):

command = isso -c /opt/isso/isso.conf run
user = isso
autostart = true
autorestart = true
stdout_logfile = /opt/isso/supervisor.log
redirect_stderr = true
environment = LANG=en_US.UTF-8,LC_ALL=en_US.UTF-8

and, finally, run the thing:

$ sudo supervisorctl reread && sudo supervisorctl update
$ sudo supervisorctl start isso

(Now compare it to this atrocity.)

Afterwards, we can make sure that all is good in the world by checking if curl http://localhost:8001/js/embed.min.js returns some minified JavaScript gibberish.

As we established (and checked! -- remember kids, testing is important), Isso now runs in the background and is available at http://localhost:8001/. Let's make sure the webserver knows that. Again - I like Nginx, our company server is running Apache, so I'll cover both. The example in the Isso docs actually proxies it to a separate domain (like, but that seems like too much hassle for my taste, so we'll stick with a sub URI like

(Per my original assumptions, you managed to create a website, which means that you had to configure the webserver, right? Right? Anyway, that's what I'm still assuming.)

So all we need to do now is add one of the snippets below to our existing configuration:


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


<Location "/isso">
    ProxyPass "http://localhost:8001"
    ProxyPassReverse "http://localhost:8001"

Restart it, cross your fingers and visit Recognize that minified JavaScript gibberish? If you actually do, then I'm a bit concerned - you shouldn't be able to recognize that. If you recognize it as some minified JavaScript gibberish, then everything's fine and you have only one step left - adding the HTML code to your template:

<script data-isso="//"

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

Even better - you can skip the last step if you for example use a Pelican theme that supports Isso, like let's say these two.

That's it. Yes, you made it to the end. Congrats. I hope it worked, or at least helped you in some way. If not then hire us and we'll do it for you for a small price of one million dollars. Or you can leave a comment and we'll try to help you. Either option is fine, really.