Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

A Riak-based Wiki-like application.

tree: 7fa82ea28b

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 apps
Octocat-spinner-32 rel
Octocat-spinner-32 .gitignore
Octocat-spinner-32 .hgignore
Octocat-spinner-32 LICENSE license headers April 16, 2010
Octocat-spinner-32 Makefile
Octocat-spinner-32 README
Octocat-spinner-32 rebar
Octocat-spinner-32 rebar.config
README
-*- 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
Something went wrong with that request. Please try again.