isso/README

109 lines
3.4 KiB
Plaintext
Raw Normal View History

2012-10-17 20:44:35 +00:00
Isso Ich schrei sonst
=======================
You love static blog generators (especially [Acrylamid][1] *cough*) and the
2012-12-16 13:00:40 +00:00
only option to interact with the community is [Disqus][2]. 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.
2012-10-17 20:44:35 +00:00
[1]: https://github.com/posativ/acrylamid
[2]: http://disqus.com/
2012-12-16 12:55:18 +00:00
Current Status
--------------
2012-10-17 20:44:35 +00:00
2012-12-16 12:55:18 +00:00
- `nosetests specs/` ⇾ *Ran 17 tests in 0.491s*
2012-12-16 13:00:40 +00:00
- `(cd /path/static/html/ && isso)` ⇾ fire up your browser and visit `localhost:8080`
2012-10-17 20:44:35 +00:00
2012-12-16 12:55:18 +00:00
Features/Roadmap
----------------
2012-10-17 20:44:35 +00:00
2012-12-16 12:55:18 +00:00
- [x] lightweight backend (SQLite)
- [ ] transparent backend (JSON)
- [x] simple JSON API, hence comments are JavaScript-only
- [x] create comments and modify/delete within a time range as user
- [ ] Ping/Trackback support
- [x] simple admin interface
2012-12-16 12:55:18 +00:00
- [w] easy integration, similar to Disqus
2012-12-16 13:00:40 +00:00
- [ ] spam filtering using [http:bl][3]
[3]: https://www.projecthoneypot.org/
2012-12-16 12:55:18 +00:00
Development
-----------
2012-12-16 13:00:40 +00:00
*Note:* This project is proudly made with the Not Invented Here syndrome,
instead of `werkzeug` or `bottle` it uses about 150 lines to manage WSGI
2012-12-16 13:00:40 +00:00
and instead of JQuery it uses ender.js.
2012-10-25 14:20:16 +00:00
2012-12-16 13:00:40 +00:00
You'll need [2.6 ≤ python ≤ 2.7][4], [ender.js][5] and [YUI Compressor][6].
Then run:
2012-10-25 14:20:16 +00:00
$ git clone https://github.com/posativ/isso.git && cd isso/
$ make init
$ make js
2012-12-16 12:55:18 +00:00
$ isso
2012-10-25 14:20:16 +00:00
2012-12-16 12:55:18 +00:00
Then go to <http://localhost:8080/static/post.html> and write a comment :-)
2012-10-25 14:20:16 +00:00
2012-12-16 13:00:40 +00:00
[4]: http://python.org
[5]: http://ender.no.de/
[6]: http://developer.yahoo.com/yui/compressor/
2012-12-16 12:55:18 +00:00
Installation
------------
2012-10-17 20:44:35 +00:00
2012-12-16 12:55:18 +00:00
Still a TODO, but later it's simply `easy_install isso`.
2012-10-17 20:44:35 +00:00
2012-12-16 12:55:18 +00:00
Migration from Disqus
---------------------
Go to [disqus.com](https://disqus.com/) and export your "forum" as XML. If you
use Firefox and you get a 403, try a webkit browser, Disqus did something very
weird with that download link. Next:
$ isso import /path/to/ur/dump.xml
2012-12-16 13:00:40 +00:00
That's it. Visit your admin page to see all threads. If it doesn't work for
you, please file in a bug report \*including\* your dump.
2012-12-16 12:55:18 +00:00
API
---
2012-10-17 20:44:35 +00:00
2012-10-23 19:09:51 +00:00
To fetch all comments for a path, run
2012-10-17 20:44:35 +00:00
2012-12-16 12:55:18 +00:00
$ curl http://example.org/comment/foo-bar/
2012-10-17 20:44:35 +00:00
2012-12-16 13:00:40 +00:00
To write a comment, you have to POST a JSON dictionary with the following
key-value pairs. Text is mandatory otherwise you'll get a 400 Bad Request.
You'll also get a 400 when your JSON is invalid.
2012-10-17 20:44:35 +00:00
2012-10-23 19:09:51 +00:00
Let's say you want to comment on /foo-bar/
2012-12-16 12:55:18 +00:00
$ curl http://example.org/comment/foo-bar/new -X POST -d \
2012-10-17 20:44:35 +00:00
'{
"text": "Lorem ipsum ...",
"name": "Hans", "email": "foo@bla.org", "website": "http://blog/log/"
2012-10-23 19:09:51 +00:00
}'
2012-10-17 20:44:35 +00:00
2012-12-16 13:00:40 +00:00
This will set a cookie, that expires in a few minutes (15 minutes per default).
This cookie allows you do modify or delete your comment. Don't try to modify
that cookie, it is cryptographically signed. If your cookie is outdated or
modified, you'll get a 403 Forbidden.
2012-10-17 20:44:35 +00:00
2012-12-16 13:00:40 +00:00
For each comment you'll post, you get an unique cookie. Let's try to remove
your comment:
2012-10-17 20:44:35 +00:00
2012-12-16 12:55:18 +00:00
$ curl -X DELETE http://example.org/comment/foo-bar/1
2012-10-17 20:44:35 +00:00
2012-12-16 13:00:40 +00:00
If your comment has been referenced by another comment, your comment will be
cleared but not deleted to retain depending comments.
2012-10-17 20:44:35 +00:00
2012-12-16 12:55:18 +00:00
Alternatives
------------
2012-10-17 20:44:35 +00:00
- [Juvia](https://github.com/phusion/juvia) Ruby on Rails
- [Tildehash.com](http://www.tildehash.com/?article=why-im-reinventing-disqus) PHP
- [SO: Unobtrusive, self-hosted comments](http://stackoverflow.com/q/2053217)