Grok Community Documentation version 1.2

Getting started with Dolmen

Author:Vincent Fretin
Contributors:Aroldo Souza-Leite
Version:This tutorial has been tested with dolmenproject 1.0a3 and Dolmen 0.5.4.

(last modified: 2020-01-17 10:00:04)

Dolmen is set of thin enhancement layers, that is, very modular, task specific libraries, based on Grok. Among other things, you can use the Dolmen libraries to gradually create a Grok based CMS.

Dolmen is strongly based on Grok, but you don’t need to have experience with Grok to start working with Dolmen. This tutorial can also be seen as manual for creating your first Grok site and start playing with Grok using a Dolmen site (or simply a Dolmen) as a Grok sample site.

Here you will learn how to create your first Dolmen render it in the browser. You do it by first creating a Dolmen project on the file system using the dolmenproject script. For this, you have to install a Python virtual environment, activate it and then install dolmenproject in this environment.

The examples in this tutorial are done on the operating system Linux Ubuntu, a Linux distribution based on Debian. But as Python and Grok run independently from the operating system, it should be easy to take virtually the same steps on a MacOS or MSWindows machine.

Preconditions

In order to install a Dolmen for the first time, you need:

  • Python-2.6 (see Python)
  • the Python tool virtualenv installed in your system Python (see virtualenv)
  • a separate Python virtual environment
  • the Python imaging tool PIL installed for your installeed Python.
  • the tool dolmenproject installed in the Python virtual environment

Python, lxml and PIL

We need to install some packages via the package manager:

$ sudo apt-get install build-essential python2.6 python2.6-dev \
    python-imaging libxslt1-dev libxml2-dev

We use python-imaging to install PIL and libxslt1-dev libxml2-dev to be able to build lxml.

The Python virtual environment

The main Python system must include a tool called virtualenv that creates a separate Python environment. A separate Python virtual environment can be used among other purposes for testing a Python library without changing the main Python configuration on your computer. For the installation of the virtualenv utility in your main Python system see the virtualenv documentation on the Python site.

Here and in then next examples, $ stands for your usual operating system’s usual command prompt, whereas (dolmenenv)$ stands for the prompt indicating that the virtual environment is active.

$ virtualenv -p /usr/bin/python2.6 dolmenenv
$ source dolmenenv/bin/activate
(dolmenenv)$

A label (dolmenenv) will appear on the left of your usual command prompt. This is a sign that you are working in the separate Python environment you created. In order to deactivate it, type deactivate and you will see your usual operating system prompt again. Now change the current directory to the location where you want to create Dolmen projects:

(dolmenenv)$ cd /path/to/my/projects

Installing the dolmenproject script

You can easy_install dolmenproject:

(dolmenenv)$ easy_install dolmenproject

Development version of dolmenproject

If you want to work on dolmenproject, you can install it from the git repository.

(dolmenenv)$ git clone git://devel.dolmen-project.org/dolmenproject.git
(dolmenenv)$ cd dolmenproject
(dolmenenv)$ python setup.py install

To update dolmenproject afterwards, issue git pull in the directory and run python setup.py install again.

(dolmenenv)$ git pull
(dolmenenv)$ python setup.py install       # with the dolmenenv enabled.

Using dolmenproject to create the Dolmen project

Make sure you changed to the directory where you want to create your Dolmen projects and that the Python virtual environment (dolmenenv) is active.

Create a Dolmen project by calling dolmenproject with the project name as a parameter. Here we call it MyDolmen but of course you can give it a name of your choice.

(dolmenenv)$ dolmenproject MyDolmen

You can use an older KGS like this:

(dolmenenv)$ dolmenproject \
--version-url="http://www.dolmen-project.org/kgs/dolmen-kgs-0.5.4.cfg" \
MyDolmen

Or use development version like this:

(dolmenenv)$ dolmenproject \
--version-url="http://gitweb.dolmen-project.org/misc.git?a=blob_plain;f=dolmen-kgs-1.0dev.cfg;hb=HEAD" \
MyDolmen

In the process of creating the Dolmen project, you are asked for a user name and a password as a site adminstrator. You have to remember these credentials later on.

Disable the virtual environment:

(dolmenenv)$ deactivate

Then change to the MyDolmen project root to bootstrap your project with distribute (-d option) and run buildout:

$ cd MyDolmen
$ python2.6 bootstrap.py -d
$ bin/buildout

Run the Dolmen site like this:

$ bin/paster serve parts/etc/deploy.ini

For development purpose, run it with the following command:

$ bin/paster serve --reload parts/etc/debug.ini

This command causes the Dolmen process to be more verbose, so that you are told about what is happening through messages in the console.

Point your browser to http://localhost:8080 to see the page being served. You are going to be asked for your credentials. Here you can test your Dolmen server by creating a test Dolmen application (give it some name like mydolmen).

Then click on ‘mydolmen’ to see your first Dolmen application.

There is almost no content in ‘mydolmen’, but it’s already a fully functional Dolmen application.

Use a skin

To use a skin for your Dolmen project, you have to do some work on setup.py of the MyDolmen root and then change the working directory to src/mydolmen to do some work there.

$ cd src/mydolmen

Add to setup.py:

menhir.skin.lightblue

Add to configure.zcml:

<include package="menhir.skin.lightblue" />

and replace:

<!-- Skin  -->
<includeOverrides
    package="dolmen.app.layout"
    file="skin.zcml"
    />

by:

<!-- Skin  -->
<includeOverrides
    package="menhir.skin.lightblue"
    file="skin.zcml"
    />

You can try the menhir.skin.snappy skin too, but it may not be up to date with the latest Dolmen changes.

You can remove ‘dummydolmen’ by pointing your browser back to http://localhost:8080 , checking the ‘delete’ box and submitting it. You will implement your Dolmen application in the following parts of this tutorial.