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
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 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
name =
dbpath = /db/
# Replace with your domain
host =
notify = smtp
reply-notifications = true

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

enabled = true

require-author = true

# I'm using sendgrid as it was the easiest setup
username = apikey
password = <sendgrid api key>
host =
port = 465
security = ssl
to = <>
from = "isso" <>

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.

<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:

Page with a lot of comments
Disqus Isso Difference
Performance grade 91% 95% +4%
Page size 416.3 KB 179.4 KB -236.9 KB
Load time 211 ms 159 ms -62ms
Requests 22 15 -7
Page with no comments (different test server location)
Disqus Isso Difference
Performance grade 91% 95% +4%
Page size 392.0 KB 149.5 KB -242.5 KB
Load time 391 ms 383 ms -8ms
Requests 18 15 -3

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