Personal tools
You are here: Home Documentation Tutorials Musical Performance Organizer - Part 1 Setting Up The Environment

Setting Up The Environment

Configuring the project environment, understanding where files are located, and how to run application and test code.
The first in a series of tutorials that will build a reasonably complex application, starting from a simple prototype and evolving it into a finished application. The tutorial will touch on many practical aspects of building the application and demonstrate how to combine the various components that are available in Grok into a finished product.
Page 2 of 6.

Installing Grok

Instructions for installing Grok can be found in the Grok Tutorial . We are going to use a helper application called "GrokProject" to set up our sample project. This is the recommended way to install a Grok application as it puts in place all the scripts and tools you will need to build, run and deploy your application.

GrokProject is installed by running a tool called "easy_install", which will download GrokProject from a repository on the internet called PyPI (the Python Package Index). Most of the application code that you will install using Grok will come from this source.

While it is very easy to use easy_install, there can be problems if you use it to install all the software you need for your Grok project and, perhaps, other Python based software you may use. The versions of different component pieces will sometimes conflict and it can be difficult to figure out why your project fails due to an update of some other package.

NOTE: As of Grok 1.2 you do not need to use virtualenv, Grok is automatically isolated from other python libraries.

In order to avoid these problems we are going to create our sample project in a "virtual environment" which will isolate it from other python libraries. Fortunately, there is an easy way to create this isolated environment using a tool called virtualenv .

Some Linux distributions provide virtualenv as a standard install for the operating system. (On Debian/Ubuntu it is called "python-virtualenv") If this is available for you, you do not need to install "easy_install" to your main Python installation, as virtualenv will include its own copy.

If this option is not available, you will need to install "easy_install" following the directions in the Grok Tutorial . There is a tutorial dedicated to explaining how virtualenv is used with Grok and how to create a project inside the environment.

Creating the Virtual Environment

Create the sample project in your home directory in a new sub-directory, called "grok". (For Windows, use "My Documents\grok". For others use "~/grok".)

Change into this new directory and create the virtual environment and our sample project. If you have difficulties or receive error messages, refer to the tutorial links above as they do provide answers to common problems.

$ cd ~/grok
$ virtualenv --no-site-packages virtualgrok
$ source virtualgrok/bin/activate
(virtualgrok)$ easy_install grokproject
(virtualgrok)$ cd virtualgrok

Preparing for the Sample Project

The grokproject application will set up your project so that it can be further developed using a tool called "zc.Buildout". This tool creates an environment that allows you to test, debug, and deploy your project code. Grokproject will even run Buildout for you the first time so that the new application is ready to run and display a simple welcome screen in a web browser.

If you have never run buildout before, it will download between 80 and 90 MB of code to create your initial Grok project. By default, it will create a cache of the source code it downloads in your home directory under ~/.buildout/eggs. This will prevent having to re-download this code every time you run buildout or grokproject.

You can change the location of this cache by creating or altering a file named ~/.buildout/default.cfg. Simply include the following lines:

eggs-directory = /path/to/directory

Creating the Sample Project using GrokProject

Now you are ready to run grokproject. If this is your first time running grokproject, be prepared to wait several minutes while the necessary source code is downloaded from PyPI. (Creating future projects will be much quicker because the source code will be cached locally.)

(virtualgrok)$ cd ~/grok/virtualgrok
(virtualgrok)$ grokproject music
Enter user (Name of an initial administrator user): grok
Enter passwd (Password for the initial administrator user): grok

The new sample project is located at ~/grok/virtualgrok/music and now ready for us to try out.

Note: Now that the project is created, the buildout configuration will point to the virtual Python installation within our environment. We no longer need to source the "activate" script while working with our project.

Becoming Familiar With The Project

Take a moment to become familiar with the sample project you just created by browsing through the project directory.

Directory and File Structure

Under "music" will will find several directories and files.

Contains various script files to control your project. The ones that you will use most often are:
  • buildout: to rebuild your project if you make changes to its dependencies.
  • music-debug: gives you an interactive debug prompt (Python interpreter) with your project environment already configured. You can inspect and modify your stored objects and simulate browser requests.
  • paster: to run your project. Initially, it will run in its own web server process, but paster can deploy your application in many ways.
  • test: runs every unit test and functional test it can find and reports the results.
Contains configuration templates for this project's installation. The template file names end with ".in". These templates are copied to the project's parts/etc directory when buildout is run. If you want to make changes to the configuration that are available the first time you run buildout or are maintained even when you reconfigure your project by running buildout again, you need to modify these files.
This directory is generated the first time you run buildout. The "etc" subdirectory contains the configuration files which were generated from the configuration templates. The generated file are the one that actually effect configuration when you run the application. If you make changes to these files you must restart the application in order for them to take effect. Whenever you run buildout, any changes to these files are overwritten.
  • debug.ini and deploy.ini: configuration scripts for paster. They determine thing like what network port and address the web server will be bound to. The debug.ini will present more meaningful error messages through your browser should an error occur. Edits to this file will be lost the next time you run buildout.
  • site.zcml: contains some basic security directives for your project. The user name and password you supplied to grokproject are recorded here. (More advanced security schemes can be implemented later to avoid having clear-text passwords on the file system.) Edits to this file will be lost the next time you run buildout.
Contains the source code for your application and configuration information to be used if you want to deploy your code as a Python egg (music.egg-info).
Contains the source code you write.
  • the starting point for your application. You can place all your source code in this file or break it up into multiple files.
  • app.txt: a very simple functional test of the application. More tests can be added to this file or you can add tests to other text files in this directory and the test runner will find them.
Contains html template files that grok will associate with your code in order to publish it on the web.
  • a simple template created by grokproject that presents a welcome message. We will see this template in action when we run our project.
A directory where you can place static files that you want available to your application. This may include image files, cascading style sheets, or JavaScript files.
Contains the object database files, web server log files, and any file storage (BLOB's) maintained by the application. In a production environment, you will want to include this directory in a regular backup process as it contains all the user-entered content.

Configuration Files

There are a few configuration files you should be familiar with.
Located in the main project directory, this file contains metadata about your project including its version and what other packages it requires to run.
Located in the main project directory, this file allows you to customize the buildout process. You can specify a project-specific location for the cached source code. You can specify other places to look for source code, or you can combine several applications into one buildout processes. Specifics about buildout can be found in the Introduction to zc.buildout tutorial.
Located in the main project directory, this file initially contains a list of specific version of software that are known to work together (aka "Known Good Set" or KGS).

Run Tests and Start the Web Server

Now that we have had a look around, it is time to do something with the application we created. We will start by running the simple tests created with the project.

$ cd ~/grok/virtualgrok/music
$ ./bin/test

Running tests at level 1
Running music.FunctionalLayer tests:
  Set up music.FunctionalLayer in 1.523 seconds.
  Ran 3 tests with 0 failures and 0 errors in 0.158 seconds.
Tearing down left over layers:
  Tear down music.FunctionalLayer ... not supported

The tests that were run are located in ~/grok/virtualgrok/music/src/music/ Take a look at this file, if you would like to see what was tested.

Now it is time to start the web server. By default, the web server will be available at http://localhost:8080 . If you already have a program that is using that port, you will have to assign a new port using parts/etc/debug.ini or parts/etc/deploy.ini.

Note: These changes will be lost the next time your run buildout, so if you want permanently change the default port, you will need to modify etc/ and/or etc/ and run buildout again.
$ cd ~/grok/virtualgrok/music
$ ./bin/buildout
Note: If you want this server to be accessible from another computer you will have to modify the 'host' entry in the above files to your computer's host name, its IP address, or to (bound to all addresses).

Run the server:

$ cd ~/grok/virtualgrok/music
$ ./bin/paster serve parts/etc/deploy.ini
Starting subprocess with file monitor
2009-03-06T22:12:40 WARNING root Developer mode is enabled: this is a
security risk and should NOT be enabled on production servers. Developer
mode can be turned off in etc/zope.conf
Starting server in PID 16637.
serving on

Point a web browser at http://localhost:8080 and you will be prompted for a user name and password. Enter the values that you entered when you ran grokproject. (Should be user name = grok and password = grok.)

You are now in the Grok Admin User Interface.


We will explore the Admin UI in greater detail later. For now, understand that this is a place where you can create instances of your application. Each instance will be separate and can be accessed by name as the first part of the URL following the host name.

For the Musical Performance Organizer, several bands could use the same application on the same web server by having separate instances. (There are some problems to consider in order to use that strategy and we will explore those later.) For now, this gives us a quick way to setup and delete entire instances as we are developing our application.

Create an application instance by typing "band" in the "Add Application" text box and press "Create".

You will now see the instance listed in the "Installed Applications".


Click on the "band (Music)" link to view the instance at http://localhost:8080/band .

You should see the following text:


Your Grok application is up and running. Edit music/app_templates/ to change this page.

The application is up and running. Now we need to start modifying it to meet our requirements.