basho-labs/wriaki

A Riak-based Wiki-like application.

-*- mode:org -*- Wriaki: the Riak-based Wiki

Overview

Wriaki is a wiki-like web application, intended to illustrate a few strategies for storing data in Riak.

Installation

Prerequisites

To build Wriaki, you will need Erlang OTP release R13B03 or later, Mercurial, and Git.

To run Wriaki, you will need Riak, Python and the Wiki Creole Python package.

Riak

The easiest way to get Riak is to download a pre-built distribution from [http://downloads.basho.com/riak/]. Any version 0.9.1 or newer should work.

As of version 0.10.0, Riak offers two interfaces, HTTP and Protocol Buffers. Wriaki supports both interfaces. If you plan on using the HTTP interface you must be careful of port conflicts with Wriaki if they are run on the same machine. By default, Riak uses port 8098 on localhost while Wriaki uses port 8000. If you leave the default settings you do not need to worry about port conflicts.

Wriaki can also use features of Riak Search, if you have that installed. See the Configuration section for more information.

Wiki Creole

The easiest way to get Wiki Creole is by using easy_install:

$ easy_install Genshi
$ easy_install Creoleparser

Downloading and Building Wriaki

To setup Wriaki, first clone the source:

$ git clone git://github.com/basho/wriaki

Next, change to the source directory and run make:

$ cd wriaki
$ make rel

Configuration

After building, you should have a rel/wriaki/ subdirectory under the source directory. Configuration for wriaki is stored in rel/wriaki/etc/app.config.

The settings that Wriaki knows about are:

salt

the “salt” used for encrypting user passwords

riak

the connection information for Riak For Protocol Buffers, use: {pb, {Host, Port}} For HTTP, use: {http, {Host, Port, Prefix}} http://<Host>:<Port>/<Prefix>/Bucket/Key

web_ip

the IP to bind Wriaki’s webserver to

web_port

the TCP port Wriaki should listen on

log_dir

the directory to write Wriaki’s access log in

search_enabled

expose full-text article search through use of Riak Search features. Only set to ‘true’ if you are running Riak Search instead of vanilla Riak.

Running

Before running Wriaki, ensure that your Riak cluster is started and reachable.

Next, run the wriaki script in your rel/wriaki/bin/ subdirectory:

$ rel/wriaki/bin/wriaki console

To start Wriaki in the background, use start instead of console on that command line.

Data Layout

There are four basic objects in the Wriaki system: article, archive, history, and user.

Article

One article object exists for each page on the wiki.

Key: article title

The key for an article object is the title of the wiki page, base64 encoded.

Bucket: article

Articles are stored in the article Riak bucket. The article bucket is configured for allow_mult=true. This is done to allow multiple users to edit an article concurrently. If they save at the “same” time, the article object will contain siblings on the next read, and Wriaki will warn the viewer that there are multiple versions of the article that are currently considered “the latest.”

Body: json

The value of an article object is JSON, with the fields:

text

(string) content in wiki markup format

message

(string) commit message

version

(string) version hash

timestamp

(int) edit date

Headers

Articles use one link to track which user created that version of the object. The link will be to an object in the user bucket, and will be tagged editor.

Merge: ask user

When conflicting writes to an article are found, the user will be given the option to view the version they want. Editing the article will resolve the conflict.

Archive

One archive object exists for each version (past and present) of each article.

Key: version.article

The key for an archive object is the version hash appended with the article object key, separated by a dot.

Bucket: archive

Archive objects are stored in the archive bucket. The bucket is left as allow_mult=false.

Body: json

The value of an archive object is exactly the same as that of an article object.

Headers

The archive object has the same link header as the article object.

Merge: last write wins

Archive objects should be write-once, due to their key generation, and thus will not need a merge strategy.

History

One history object exists for each page on the wiki. The purpose of the history object is to hold links to all versions of each article object.

Key: article

The key for the history object is the same as the key for the article object.

Bucket: history

History objects are stored in the history bucket. The bucket is configured for allow_mult=true to allow multiple users to add article versions (thus updating the history) concurrently.

Body: empty

History objects have no data in their bodies.

Headers

History object have one link for each version an article has had. The links will target objects in the archive bucket, and will be tagged with the timestamp of the article version.

Merge: set-union links

Merging two versions of an archive object is simply set-unioning the list of links.

User

One user object exists for each registered user of the wiki. This object keeps track of the user’s password and other data.

Key: username

User objects are keyed by url-encoded usernames.

Bucket: user

User objects are stored in the user bucket. The bucket is left as allow_mult=false because only the user should be updating that user’s object (no concurrent writing).

Body: json

The value of a user object is JSON with the fields:

email

(string) email address

password

(string, base64) encrypted

bio

(string) short biography

Headers

User object have no headers.

Merge: last write wins

No merge is needed for user objects. They should only be edited by their owners, and last-write-wins will be good enough to handle that.

Session

One session object exists for each logged-in user. This object keeps track of when the user last pinged the wiki, and when they will be automatically logged out.

Key: session token

Session objects are keyed by a randomly-generated session token.

Bucket: session

Session objects are stored in the session bucket. This bucket is left as allow_mult=false because only the active session should be updating it.

Body: json

The value of a session object is JSON with the fields:

username

(string) username for the user of this session

expiry

(integer) time at which the session will expire

Headers

Session objects have no headers.

Merge: last write wins

No merge is needed for session objects. They should only be editred by the active session, and last-write-wins will be good enough to handle that.

Web Resources

Wriaki exposes the following resources:

/user

login page, GET-only

/user/<username>

User’s settings

GET: with no query parameters returns a page of public information about the user

with query parameter ?edit, returns a form for the user to update their information (user is redirected to non-query-parameter URL if this is not their login)

PUT: change user data

POST: login

/user/<username>/<sessionid>

Session information

GET: get expiry time of the session, also extends the session’s expiry

DELETE: remove the session, “logout”

/wiki/<page name>

Wiki page

GET: with no query parameters returns the rendered wiki page

with query parameter ?edit, returns a form for the user to edit the page

with query parameter ?history, returns a list of the known versions of the object

with query parameter ?v=<version>, returns the page rendered for the requested version

with query paramaters ?diff&l=<left_version>&r=<right_version> returns a line-by-line difference of the given versions

PUT: store a new version of the wiki page

POST: preview a new version of the wiki page

/static/*

serve static files from disk

GET: retrieve the specified file