Replacing Disqus comments with Isso

This site used to use Disqus comments but, while Disqus is very convenient, it isn’t great for privacy or performance. After some consideration, I decided to change.

After some searching, I found Isso. Isso supports pre-approving comments (good for preventing spam), is relatively light and stores the comments in a local SQLite database, so no database setup is required.

Isso is written in Python, which can be a pain to install. Python virtual environments significantly improve things, but I’m not a massive fan of them on servers. In my opinion, the easiest way is to install it via Docker, which has the benefit of keeping Isso contained from the rest of the server.

Installing Isso using Docker

Isso doesn’t seem to have an official DockerHub image, so the safest way is to build it yourself.

To build it, first, download the code:

git clone git@github.com:posativ/isso.git
cd isso

Then run the Docker build command:

docker build -t isso .

Once built, the image can be pushed to docker hub / other repository and then pulled to the server, or the image can be pushed directly to the server by running:

docker save isso | bzip2 | pv | ssh user@example.com docker load

The above saves the image, pipes it through bzip to compress it, pipes it through pv to show an upload progress bar and finally pipes it to the docker load command on the remote host.

Next, create an isso.cfg configuration file. It doesn’t matter where it is saved. I chose to put it in a directory called isso below the public_html directory:

# isso/isso.cfg
[general]
name = example.com
dbpath = /db/example.com.db
# Replace example.com with your domain
host =
    https://example.com
    https://www.example.com
notify = smtp
reply-notifications = true

[server]
listen = http://localhost:8621
# reload reloads Isso after code changes and
# profile does some profiling of code, neither
# should be used in production
reload = off
profile = off

[moderation]
enabled = true

[guard]
require-author = true

[smtp]
# I'm using sendgrid as it was the easiest setup
username = apikey
password = <sendgrid api key>
host = smtp.sendgrid.net
port = 465
security = ssl
to = <you@example.com>
from = "isso" <isso@example.com>

[admin]
enabled = true
password = <password>

Importing Disqus Comments

Next, to import the Disqus comments, create an export via Disqus Admin -> Moderation -> Export. The export will be a gzipped XML file but be warned, it can take a while for Disqus to generate it.

You will need to decompress the XML file before importing into Isso.

To import the XML export, run:

# Replace /path/do/isso/directory with the directory
# where the config file is and where the DB should be created.
# Place the Disqus export in the directory and rename it
# to comments.xml
docker run --rm -it \
    -v /path/do/isso/directory:/db \
    -v /path/do/isso/directory:/config \
    isso \
    /isso/bin/isso \
    -c /config/isso.cfg \
    import --empty-id /db/comments.xml

This should generate the DB file with the name specified in the config which can be uploaded to the appropriate location on the server.

Starting Isso

Once done, the Isso image can be started by running:

docker run -d \
    --restart=always \
    --name isso \
    -p 8621:8080 \
    -v /path/to/isso/config/directory:/config \
    -v /path/to/isso/database/directory:/db isso

If there is no database in the database directory, Isso will create one. So if your comment DB is blank, it may be because the path to the DB is wrong.

Setting up the Nginx reverse proxy

Isso could be set up as a subdomain or to a path. I chose the path option for this site.

The Nginx reverse proxy settings to load Isso on the path /isso are:

# Use ^~ to make higher precedence than other locations
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:8621/isso;
}

Once added, reload Nginx:

# Use nginx -t test the config before attempting to reload
# this prevents any downtime if the config has errors
nginx -t
service nginx reload

That’s it! Just add the Isso script and HTML tags, and it should work.

<script
    data-isso="https://www.example.com/isso/"
    src="https://www.example.com/isso/js/embed.min.js"></script>
<section id="isso-thread"></section>

Updating Isso

To update Isso in the future, download the updated code and repeat the build and push steps.

Then, on the server, then run:

# Stop and remove the Isso container
docker stop isso
docker rm isso

# Start a new instance of Isso using the updated image
docker run -d \
    --restart=always \
    --name isso \
    -p 8621:8080 \
    -v /path/to/isso/config/directory:/config \
    -v /path/to/isso/database/directory:/db isso

# Remove the old image
docker system prune images

Alternatively, you could use Docker compose, which can reduce the above to docker-compose up once it has been set up.

Performance comparison

The main reason for switching to Isso was to improve privacy, but it also had a modest effect on the overall performance of this site.

Results of a quick test using Pingdom Tools:

Not massive, but definitely worthwhile, and the performance increase is likely even bigger on mobile.

• Comments
• Hugo