isso/README.md

Isso – Ich schrei sonst

You love static blog generators (especially Acrylamid cough) and the only option to interact with the community is Disqus. There's nothing wrong with it, but if you care about the privacy of your audience you are better off with a comment system that is under your control. This is, were Isso comes into play.

Screenshot @2013-09-13 | Screenshot @2013-10-03 | Try Yourself! (in case it's not crashed ;-)

Isso is not stable (pretty far from that state) and the database format may change without any backwards compatibility. Just saying.

Features

• CRUD comments
• SQLite backend
• client-side JS (currently 60kb minified (20.5 gzipped))
• I18N, available in german and english (also fallback)

Roadmap

• Ping/TrackBack™ support
• simple admin interface
• spam filtering

Installation

Requirements:

• Python 2.6 or 2.7
• NPM and Bower

For now (as long as there is no stable version), you need to manually build everything:

~> git clone https://github.com/posativ/isso.git
~> cd isso/
~> python setup.py develop

To fetch the requires JS components (and CSS framework), run:

~> cd isso/js/
~> bower install almond q requirejs requirejs-domready requirejs-text

You can now either use the JS client as-is (using require.js, see below) or compile all JS into a single file:

~> cd isso/js
~> npm install -g requirejs uglifyjs
~> r.js -o build.embed.js
~> r.js -o build.count.js

Before you start, you may want to import comments from Disqus.com:

~> isso import ~/Downloads/user-2013-09-02T11_39_22.971478-all.xml
[100%]  53 threads, 192 comments

You start the server via (try to visit http://localhost:8080/static/post.html).

~> isso run

Webserver Configuration

This part is not fun, I know. I have prepared two possible setups for nginx, using Isso on the same domain as the blog, and on a different domain. Each setup has its own benefits.

Isso on a Sub URI

Let's assume you want Isso on /isso, use the following nginx snippet

server {
    listen       [::]:80;
    listen       [::]:443 ssl;
    server_name  example.tld;
    root         /var/www/example.tld;

    location /isso {
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Script-Name /isso;
        proxy_pass http://localhost:8080;
    }
}

The Isso API endpoint is now example.tld/isso, check by curling the client JS located at http://example.tld/isso/js/embed.js.

Isso on a Dedicated Domain

...

Website Integration

Add the following two lines into your HTML header:

<link rel="stylesheet" href="http://example.tld/isso/static/isso.css" />
<script src="http://example.tld/isso/embed.min.js"></script>

To enable comments, add a <div id="#isso-thread"></div> below your post and let the magic happen :-)

To add comment count links to your index page, include count.min.js at the very bottom of your document. All links followed by #isso-thread, are updated with the current comment count.

This functionality is already included when you embed embed.min.js, do not mix embed.min.js and count.min.js in a single document.

Embed with require.js

This section is primarily for developers: The client-side JS is modularized and uses an AMD loader for execution. You can easily hack on the JS files, when using require.js:

<link rel="stylesheet" href="/static/isso.css" />
<script src="/js/config.js"></script>
<script data-main="/js/embed" src="/isso/js/components/requirejs/require.js"></script>

API

See docs/API.md.

Alternatives

• talkatv – Python
• Juvia – Ruby on Rails
• Tildehash.com – PHP
• SO: Unobtrusive, self-hosted comments