Get Started!

The instructions on this page will show you how to get the source for clckwrks, get the required javascript libraries such as jstree, json2 and jquery, and how to fork the clckwrks.com source to create your own site.

clckwrks is still in early development, so there are a few steps required. This will eventually be automated.

step 0: make sure cabal is installed and updated

Run:

cabal update

and check that:

$HOME/.cabal/bin

is in your $PATH.

step 1: get the starting template from github

git clone git://github.com/clckwrks/example-dot-org.git
cd example-dot-org

step 2: fetch the javascript dependencies

clckwrks depends on three javascript libraries:

  1. jquery
  2. json2
  3. jstree

There is a Makefile in the example-dot-org top-level source that will fetch and unpack the javascript dependencies. Just run make:

make

Alternatively, you can fetch these libraries by hand or install them via your package manager (yum, apt-get, etc). The Makefile is just for convenience.

In theory, we should probably bundle these javascript dependencies in the clckwrks cabal package itself. However, we have not yet figured out the licensing issues involved in doing that.

step 3: install runtime dependencies

clckwrks currently requires the markdown perl script and the HsColour executable to be installed.

step 4: build example-dot-org

You should now be able to test the example-dot-org server. In the example-dot-org directory run:

$ cabal sandbox init
$ cabal install
$ ./.cabal-sandbox/bin/example-dot-org-server

and point your browser at http://localhost:8000/

The executable takes a number of flags, which are documented by the --help flag. To install the server, you might also to set the hostname for the server, the port it runs on, and the paths to the required javascript files:

$ example-dot-org-server --hostname example.org --http-port 8000 --jstree-path=/path/to/jstree --json2-path=/path/to/json2 --jquery-path=/path/to/jquery

step 5: create an admin account

Click on the login link to create an account. If the login link does not show up you can go to http://localhost:8000/clck/auth/auth/login.

Now create an account for yourself. Note that the openid based methods only work if your server is accessible from the outside world. For development, you may find it easier to just create a simple username/password.

After you create an account you will want to give yourself Administrator privileges. This can be done using the clckwrks-cli tool. While the server is running invoke clckwrks-cli and point it to the socket file:

$ cabal install clckwrks-cli
$ ./.cabal-sandbox/bin/clckwrks-cli _state/profileData_socket

that should start an interactive session. If the server is running as root, then you may need to add a sudo in front.

Assuming you are UserId 1 you can now give yourself admin access:

% user add-role 1 Administrator

You can run help for a list of other commands. Type quit to exit.

step 6: install the C libraries that clckwrks-plugin-media requires

This is optional. It is only required if you want to use the media plugin in your application.

The clckwrks-plugin-media package depends on three C libraries: magic, expat, and gd.

On Debian based systems you can probably do:

apt-get install libmagic-dev libgd2-xpm-dev libexpat1-dev

On Fedora / CentOS you need:

yum install file-devel gd-devel expat-devel

For other systems, you'll need to figure out the equivalent.

Next, build and install the clckwrks-plugin-media library. And then update your Main.hs. You need to add:

import Clckwrks.Media.Plugin (mediaPlugin)

And in the initHook add a call to initPlugin:

initHook :: Text
         -> ClckState
         -> ClckwrksConfig
         -> IO (ClckState, ClckwrksConfig)
initHook baseURI clckState cc =
    do let p = plugins clckState
       initPlugin p baseURI clckPlugin
       initPlugin p baseURI mediaPlugin
       setTheme p (Just theme)
       return (clckState, cc)

It is important to initialize the mediaPlugin after the clckPlugin because the mediaPlugin uses some of the resources clckPlugin defines.

step 7: code!

Now you are ready to start customizing clckwrks to your needs! Feel free to ask questions on the mailing list or talk to us on #happs on irc.freenode.net.