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.
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.
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 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
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):
To log into user "isso" we use the following command
Installing isso with pip3
First, log into the newly created "isso" account
and install with pip3
If you need to uninstall (for whatever reason) you can do so with
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)
The contents for my configuration is below
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
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
and paste the following (editing any file paths if you used a different location for your isso.conf file)
Let's enable the service (which will cause isso to start automatically when restarting the server)
You should now be able to start, stop, check status, and restart isso using the following systemd commands:
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
First let's get there. Click on the cog icon in the top right of confluence and click General configuration:
Click the button and paste (and edit as required) the following:
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-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).
function() simply appends the isso script (which will be executed to render isso) on the page when it loads.