ISSO(1)

NAME
isso - a Disqus alternative

WHAT'S ISSO?

Isso is a lightweight commenting server similar to Disqus. It allows anonymous comments, maintains identity and is simple to administrate. It uses JavaScript and cross-origin ressource sharing for easy integration into static websites.

NO, I MEANT ISSO

Isso is an informal, german abbreviation for "Ich schrei sonst!", which can roughly be translated to "I'm yelling otherwise". It usually ends the discussion without any further arguments.

In germany, Isso is also pokémon N° 360.

WHAT'S WRONG WITH DISQUS?

No anonymous comments (IP address, email and name recorded), hosted in the USA, third-party. Just like IntenseDebate, livefrye etc. When you embed Disqus, they can do anything with your readers (and probably mine Bitcoins, see the loading times).

SETUP

  Quickstart

Assuming you have successfully installed Isso, here's a quickstart quide that covers the most common setup. Sections covered:

•   Configuration

•   Migration

•   Running Isso

•   Integration

•   Going Further

  Configuration

You must provide a custom configuration to set dbpath (your database location) and host (a list of websites for CORS). All other options have sane defaults.

[general]
; database location, check permissions, automatically created if not exists
dbpath = /var/lib/isso/comments.db
; your website or blog (not the location of Isso!)
host = http://example.tld/
; you can add multiple hosts for local development
; or SSL connections. There is no wildcard to allow
; any domain.
host =
    http://localhost:1234/
    http://example.tld/
    https://example.tld/

Note, that multiple, different websites are not supported in a single configuration. To serve comments for different websites, refer to Multiple Sites.

The moderation is done with signed URLs sent by email or logged to stdout. By default, comments are accepted and immediately shown to other users. To enable moderation queue, add:

[moderation]
enabled = true

To moderate comments, either use the activation or deletion URL in the logs or use SMTP to get notified of new comments, including the URLs for activation and deletion:

[general]
notify = smtp
[smtp]
; SMTP settings

For more options, see server and client configuration.

  Migration

Isso provides a tool for importing comments from Disqus or WordPress. You can also import comments from any other comment system, but this topic is more complex and covered in advanced migration.

To export your comments from Disqus, log into Disqus, go to your website, click on Discussions and select the Export tab. You'll receive an email with your comments. Unfortunately, Disqus does not export up- and downvotes.

To export comments from your previous WordPress installation, go to Tools, export your data. It has been reported that WordPress may generate broken XML. Try to repair the file using xmllint before you continue with the import.

Now import the XML dump:

~> isso -c /path/to/isso.cfg import -t [disqus|wordpress] disqus-or-wordpress.xml
[100%]  53 threads, 192 comments

  Running Isso

To run Isso, simply execute:

$ isso -c /path/to/isso.cfg run
2013-11-25 15:31:34,773 INFO: connected to HTTP server

Next, we configure Nginx to proxy Isso. Do not run Isso on a public interface! A popular but often error-prone (because of CORS) setup to host Isso uses a dedicated domain such as comments.example.tld.

Assuming both, your website and Isso are on the same server, the nginx configuration looks like this:

server {
    listen [::]:80 default ipv6only=off;
    server_name example.tld;
    root ...;
}
server {
    listen [::]:80;
    server_name comments.example.tld;
    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

  Integration

Now, you embed Isso to your website:

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

Note, that data-isso is optional, but when a website includes a script using async it is no longer possible to determine the script's external URL.

That's it. When you open your website, you should see a commenting form. Leave a comment to see if the setup works. If not, see troubleshooting.

  Going Further

There are several server and client configuration options uncovered in this quickstart, check out configuration/server and configuration/client for more information. For further website integration, see extras/advanced-integration.

To launch Isso automatically, check the init-scripts section from the installation guide. A different approach to deploy a web application is written here: Deployment of Isso.

  Troubleshooting

  For uberspace users

Some uberspace users experienced problems with isso and they solved their issue by adding DirectoryIndex disabled as the first line in the .htaccess file for the domain the isso server is running on.

  pkg_ressources.DistributionNotFound

This is usually caused by messing up the system's Python with newer packages from PyPi (e.g. by executing easy_install --upgrade pip as root) and is not related to Isso at all.

Install Isso in a virtual environment as described in install-interludium. Alternatively, you can use pip install --user to install Isso into the user's home.

  UnicodeDecodeError: 'ascii' codec can't decode byte 0xff

Likely an issue with your environment, check you set your preferred file encoding either in LANG, LANGUAGE, LC_ALL or LC_CTYPE:

$ env LANG=C.UTF-8 isso [-h] [--version] ...

If none of the mentioned variables is set, the interaction with Isso will likely fail (unable to print non-ascii characters to stdout/err, unable to parse configuration file with non-ascii characters and to forth).

  The web console shows 404 Not Found responses

That's fine. Isso returns "404 Not Found" to indicate "No comments".

AUTHOR
Martin Zimmermann

COPYRIGHT
2016, Martin Zimmermann