Installing, configuring, and integrating isso (commenting web app) into Confluence

This is (yet another) isso install guide but focusing specifically on integrating it into Atlassian's Confluence.

I've grown quite fond of Confluence and have seen it scale extremely well (I deployed and maintain a confluence server at work for around 70 users). I also use confluence for information and knowledge management for myself (e.g. what your reading now). I mainly use it to manage personal bits of information as well as to archive solutions to technical problems I've devised so I can easily find that information again (most of it is quite customised and not something that can be found again quickly by googling for it).

One of the problems I've encountered with it though, is that the native commenting is definitely not suited for public spaces and pages. That is, I can allow the public to comment on articles and pages, but (natively) confluence comments do not allow moderation. Everyone who has used confluence and allowed public comments soon find that a lot of spam will be posted.

I've been after a commenting system that balances the need for moderating comments before exposing them publicly - while also providing a privacy policy and framework I'm comfortable with. You might have noticed (if you visited previously) that I had integrated disqus into my confluence pages (if you really want to use disquss see this article I wrote). However, I'm not that comfortable with disqus' privacy and data collection (and use) policies (plus many people have somewhat of a disdain for disqus... disdainqus?).

Enter isso. From https://posativ.org/isso/docs:

Isso is a lightweight commenting server similar to Disqus. It allows anonymous comments, maintains identity and is simple to administrate.

It's also written in python (which many of you may be comfortable with), is fairly easy to setup on the server of your choice, and allows you to keep all commenting data on your own server and under your control. Plus, I like how it allows anonymous comments which you can moderate easily via email or via a simple admin interface that it provides. It also looks nice as well.

Check out what commenting in isso looks like by leaving a comment at the end of this article!

Below we'll run through installing isso on a simple linux server (I'm running Ubuntu 16.04 Server in this example but the process is the same or very similar for other distros), and then integrating isso into your confluence pages.

Installing isso

Installing dependencies and creating an "isso" user

Let's install some required packages with your package manager. In this example we're using ubuntu server, so we would do

sudo apt install python3 python3-dev python3-pip sqlite3 build-essential

For ease of management and segregating isso and it's config/db etc. we're going to create a separate user login for it (called "isso" that has no individual password and cannot be logged into directly):

sudo adduser isso --disabled-login --disabled-password

To log into user "isso" we use the following command

sudo su - isso

Installing isso with pip3

First, log into the newly created "isso" account

sudo su - isso

and install with pip3

pip3 install isso

If you need to uninstall (for whatever reason) you can do so with

pip3 uninstall isso

Configuring isso (server-side)

Isso only requires a single configuration file, which can be anywhere and can be named anything you want. We're going to call ours isso.conf and keep it in our isso users home folder. Let's create the conf with (I prefer vim but use our preferred text editor)

create isso config file (assumes in isso home folder)

vim isso.conf

The contents for my configuration is below

isso.conf

[general]
dbpath = /home/isso/comments.db
host = https://example.com/
log-file = /home/isso/log-isso.log
max-age = 15m
notify = stdout, smtp
reply-notifications = true

[server]
listen = http://localhost:<port-here>
public-endpoint = https://isso.example.com/
reload = off
profile = off

[moderation]
enabled = true
purge-after = 30d

[smtp]
username = example@example.com
password =<smtp-password-here>
host = mail.example.com
port = 465
security = ssl
to = isso-admin@example.com
from = example@example.com
timeout = 10

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

[admin]
enabled = true
password =<strong-password-here>

Replace those inputs above that are angle bracketed (e.g. <...>) with appropriate values.

Once we have configured isso, we can run it simply by pointing isso to our config file and using the run option

isso -c isso.conf run

Running isso as a service

Running the above every time you want to start up isso is not the most efficient approach (i.e. you'll have to remember to run isso every time you start / restart your server). Let's setup isso as a service to make it start automatically. The below example assumes your distro is using systemd.

You'll need to log out of the "isso" account back into your normal account (that has sudo privileges).

Log out of the "isso" account (usually by typing "exit" in the terminal) to get back to the account you usually use. Let's create a isso.service file.

sudo vim /etc/systemd/system/isso.service

and paste the following (editing any file paths if you used a different location for your isso.conf file)

/etc/systemd/system/isso.service

[Unit]
Description=Isso Comment Server

[Service]
Type=simple
User=isso
WorkingDirectory=/home/isso
ExecStart=/home/isso/.local/bin/isso -c /home/isso/isso.conf
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Let's enable the service (which will cause isso to start automatically when restarting the server)

sudo systemctl daemon-reload
sudo systemctl enable isso

You should now be able to start, stop, check status, and restart isso using the following systemd commands:

sudo systemctl start isso
sudo systemctl stop isso
sudo systemctl status isso
sudo systemctl restart isso

Other server config (apache reverse-proxy, SSL)

You'll need to setup a standard way to publicly access isso that you've just setup on your server. This will most likely involve using a reverse proxy (Apache or nginx etc). See Apache reverse-proxy SSL to multiple server applications for more information on doing this with Apache.

Also, the references at the end of this article cover setting up doing this with examples using Apache and nginx.

Integrating into Confluence

Once isso is setup, configured and working, it's actually rather simple to integrate it into confluence. We do this entirely by pasting some HTML/javascript into the Custom HTML section found in General configuration.

First let's get there. Click on the cog icon in the top right of confluence and click General configuration:

On the resulting page click Custom HTML on the left hand menu. This will bring you to a page with three boxes (which we can add HTML/Javascript into). We're going to be interested in the At end of BODY box (the last one).

Click the button and paste (and edit as required) the following:

<script type="text/javascript">

AJS.toInit(function(){

        // place after comments section
        AJS.$('#comments-section').after('<section id="isso-thread" data-title="' + AJS.params.pageTitle + '" data-isso-id="/pages/viewpage.action?pageId=' + AJS.params.pageId + '" style="margin-top:22px"></section>');

        (function() {
            var d = document, s = d.createElement('script');
            s.type = 'text/javascript'; s.async = true;
            s.src = 'https://isso.example.com/js/embed.min.js';
            s.setAttribute('data-isso', 'https://isso.example.com');
            s.setAttribute('data-isso-reply-notifications', 'true');
            (d.head || d.body).appendChild(s);
        })();
});
</script>
<noscript>Please enable JavaScript to view comments.</noscript>

You'll need to replace isso.example.com in the code above with your own isso subdomain/domain address.

So what's going on here? The above does two things: injects the required <section id="isso-thread"></section> after the native confluence comments, which should be disabled for anonymous users (via your space permissions by only giving 'Anonymous Access' the 'View" permission). Hence for anonymous (public) users, they will not see the native commenting system, only isso.

You'll notice in the isso section tag, we're explicitly defining both data-title and data-isso-id attributes. This is important for confluence (especially the data-iso-id attribute) as confluence provides two url formats for each page: a user-friendly format (like https://confluence.jaytaala.com/display/TKB/Responsive+embedded+videos+in+confluence) and pageId format (like https://confluence.jaytaala.com/pages/viewpage.action?pageId=1343551). It's important that isso can identify the page regardless of what url format users visit or else comments won't show on one of the page url formats.

To do this we instead identify the isso id for the page as via it's pageId. This is what data-isso-id="/pages/viewpage.action?pageId=' + AJS.params.pageId + '" does (AJS.params.pageId return the unique page id to isso).

Finally, our function() simply appends the isso script (which will be executed to render isso) on the page when it loads.

Space shortcuts

Page tree