I was hesitant to add a comment section to my blog, there are many reasons for that. Most of them are related to the fact that I don't want to deal with spam, trolls, and other issues that come with having a comment section. But I also did not like most of the solutions right in this space. I don't like the idea of having a third-party service that I don't control, I don't like the idea of having to pay for a service that I don't own, and I don't like the idea of having to deal with ads or other distractions in the comment section. Also, it is about privacy, I don't want to have to deal with GDPR and other privacy issues that come with having a comment section.

So I decided to explore the idea of having a comment section that is self-hosted, open-source, and free. I found a few options, but most of them were either too complex or too limited. I wanted something that was easy to set up, easy to use, and had all the features I needed. Then I found Isso which check all my boxes. It has the following features:

• self-hostable
• open-source
• free
• lightweight
• easy to set up
• has a simple and clean interface (admin UI is not the best, but it is functional)
• has a good set of features (like email notifications, moderation, etc.)
• has a decent documentation
• not bloated with features I don't need
• not new (so it is not likely to be abandoned in the near future)

I was able to deploy Isso on my servers and setup up comments on my zola static generator I use for this blog. There were a few things I had to take care of, mostly just write a suitable docker-compose.yml file and isso.cfg configuration file. Then it was a matter of adding a few lines of code to my Zola templates to render the comment section. There are some customizations that you can do for both server-side and client-side of Isso, but I did not need to do much. I just wanted a simple comment section that works and does not get in the way of reading the blog posts. But I like the fact that I can customize it if I want to in the future.

I will go into the details of my setup now, but if you want to see the comment section in action, you can scroll down to the bottom of this page. You will see a comment section that is powered by Isso. You can leave a comment, reply to other comments, and even upvote or downvote comments.

Server-side setup

The server-side setup is pretty straightforward. I used Docker to run Isso, so I just needed to create a docker-compose.yml file. Here is a simple example of what it looks like:

services:
  isso:
    image: ghcr.io/isso-comments/isso:release
    container_name: isso
    restart: unless-stopped
    volumes:
      - <path/to/config>/config:/config:ro
      - <path/to/db>:/db
    ports:
    - "8080:8080"

Where <path/to/config> is the path to your Isso configuration file and <path/to/db> is the path to the database where Isso will store the comments. I don't like using docker volumes, so I use a local path for the database. It is just a personal preference, you can use a volume if you want to. If you want to use a different port, you can change the PORT:8080 line to whatever port you want but keep the second part as 8080 because Isso will always run on that port inside the container.

Configuration file

The minimal configuration file for Isso is pretty simple. Here is an example of what it looks like:

[general]

# Change dbpath to /db/comments.db if running in docker!
dbpath = comments.db
host = http://localhost:8080/

Where dbpath is the path to the database file. If you are running Isso in Docker, you should set it to /db/comments.db because that is where the database will be stored inside the container. The host is the URL where Isso will be accessible, it will depend on your docker-compose.yml file and how you set up your reverse proxy. You can add more configuration options to the file, but this is the minimal setup that will work. You can find more options in the Isso documentation.

This is all you need to do to set up the server-side of Isso. You can start the container with docker-compose up -d and Isso will be running on the port you specified.

Client-side setup

The client-side setup is a bit more involved, but it is still pretty simple. You need to add a few lines of code to your Zola templates to render the comment section. Here is an example of what it looks like:

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

<section id="isso-thread">
    <noscript>Javascript needs to be activated to view comments.</noscript>
</section>

You need to replace comments.example.tld with the URL where Isso is accessible. This will render the comment section on the page. You can add this code to your Zola templates where you want the comment section to appear, usually at the bottom of the page. The location is mostly going to be page.html template, but this will depend on your Zola theme and how you want to structure your template.

I found that there is a problem with CORS when using Isso with Zola, so I had to add a few lines of code to my reverse proxy configuration to allow cross-origin requests. Here is an example of what it looks like for Nginx:

location /js/embed.min.js {
    add_header 'Access-Control-Allow-Origin' '*';
    add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
    add_header 'Access-Control-Allow-Headers' 'Content-Type, Authorization';
    try_files $uri =404;
}

This will allow cross-origin requests to the Isso JavaScript file, which is necessary for the comment section to work properly. You can find more information about CORS in the Isso documentation.

This is a minimal setup for the Isso, and it should work out of the box. You can customize it further by adding more options to the configuration file or changing the way the comment section is rendered in your templates. My only modification was to add a custom CSS rules to style the comment section to match the rest of my blog, especially to adjust to my dark theme.

I will test and see how well this experiment goes, and how well Isso works for my blog. Dealing with spam and trolls is always a concern but in such case I hope this part of isso.cfg configuration file will help if this happens

[moderation]
enabled = true
approve-if-email-previously-approved = true
purge-after = 30d

And I think it is always a good idea to add rate limit and enable guard mode to prevent abuse:

[guard]
enabled = true
ratelimit = 2
direct-reply = 3
reply-to-self = true
require-author = true
require-email = true

This will force users to provide an email address and name when leaving a comment, which they can write anything but with rate limit on both comments and comments to self, it should prevent most of the abuse. I will see how well this works in practice and adjust the settings if needed. There are some good settings you can enable, one of them is to use hashing for email addresses to prevent spam bots from harvesting them:

[hash]
salt = P0ch7co8Oh5jopo9Ol6ba907
algorithm = pbkdf2

But don't forget to change the salt value to something unique for your setup. You can generate a random string using a password manager or a random string generator.

The final good feature that I like is that I can make use of SMTP to send email notifications for new comments and replies. This is good for keeping track of the comments and replies, especially if you are moderating them. Here is an example of how to set it up in the configuration file:

[smtp]
host = smtp.example.com
port = 587
user = user@example.com
password = yourpassword
from = user@example.com

Now I hope this will be a good solution for my blog and that this setup can help someone else who is looking for a self-hosted comment section solution. I will probably write more about this setup if it evolves or if I find any issues with it. But for now, let us hope it works well and that I can keep the comment section clean and spam-free.