Setting Up The Environment

Configuring the project environment, understanding where files are located, and how to run application and test code.

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.

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.

zc.Buildout and Python Eggs

zc.Buildout is a tool used to assemble Python applications from multiple parts. It is very flexible, in that it allows you to pick all types of available applications and components from Python, from Zope, or from other projects and it will download and configure them so that you can use them with your application.

Once you have configured Buildout, the steps required to set up your application for development are very reproducible. Instead of having to instruct other developers to download and install all of your project’s dependencies before downloading and configuring your project, you can simply have them run your project’s buildout.

http://pypi.python.org/pypi/zc.buildout

You can also use Buildout to package your application so others can install it using easy_install. (Just like you did for with GrokProject.)

Eggs are how Buildout packages your Python application. Eggs are a way of bundling your code with extra information that will allow easy_install to fetch and configure any dependencies your application might have. If you are writing a web application using Grok, it will certainly have some dependencies. Depending on which additional components you choose to use in your project, it will have even more.

When you choose to use additional components in your application, you simply add them to your Buildout configuration and run the Buildout script again. The additional code you need will be downloaded automatically (usually in the form of Eggs!), and made available to your application.

http://peak.telecommunity.com/DevCenter/PythonEggs

The easiest place to find applications and components (packaged as Eggs) for use with Buildout, is the Python Package Index or PyPI. This index archives the version history of thousands of Python projects. If you meet the requirements, you can even upload your application to PyPI to make it easily available to everyone.

http://pypi.python.org/pypi

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:

[buildout]
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” we will find several directories and files.

bin
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.
etc
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.
parts
Contains the object database files and web server log files. It also contains an “etc” subdirectory which has the actual configuration files used when running the application.
  • 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.
src
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).
src/music
Contains the source code you write.
  • app.py: 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.
src/music/app_templates
Contains html template files that grok will associate with your code in order to publish it on the web.
  • index.pt: a simple template created by grokproject that presents a welcome message. We will see this template in action when we run our project.
src/music/static
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.

Configuration Files

There are a few configuration files you should be familiar with.

setup.py
Located in the main project directory, this file contains metadata about your project including its version and what other packages it requires to run.
buildout.cfg
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.
versions.cfg
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.
  Running:
...
  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/tests.py. 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/debug.ini.in and/or etc/deploy.ini.in 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 0.0.0.0 (bound to all addresses).

Run the server:

$ cd ~/grok/virtualgrok/music
$ ./bin/paster serve 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 http://127.0.0.1:8080

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.

tutorials/musical_performance_organizer/GrokAdminInitial.png

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”.

tutorials/musical_performance_organizer/GrokAdminTestApp.png

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

You should see the following text:

Congratulations!

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

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