Fetching contributors…
Cannot retrieve contributors at this time
151 lines (104 sloc) 5.5 KB



/!\ Since we have a hard dependency on Pyramid 1.3x which is not released
yet, we have to force the dependency to Pyramid 1.3a5 in your application (Pyramid 1.3a5 is last version available at the time of writing
this doc).
So please edit the ````, and update Pyramid dependency in
``install_requires`` so that it looks like ``'pyramid>=1.3a5'``.

Getting started

First, we will check that your project is functionnal. You could follow instructions available in the README.txt which has been generated by the "alchemy" scaffold, but since it makes use of virtualenv whereas buildout is the deploy/install tool of choice in c2c_pyramid projects, we'll give instructions to use buildout directly.

Prior to using Buildout, its script should be run at the root of the application:

$ cd /path/to/directory
$ python --version 1.5.2 --distribute \
    --download-base \

Then install the application by using buildout:

$ ./buildout/bin/buildout install eggs


The previous buildout command only executes the ``[eggs]`` part which is
the minimum required to install your application and its dependencies.

Once the application has been installed, you should create and populate the database:

$ ./buildout/bin/populate_PapyrusSample development.ini

Note that the previous command has generated a SQLite database in PapyrusSample.db. Then you can launch pserve:

$ ./buildout/bin/pserve development.ini
Starting server in PID 3453.
serving on

Let's open in your browser, you should see a nice example page which comes from the "alchemy" scaffold. This page gives you pointers to the pyramid documentation.


Hit ``Ctrl + c`` to stop the ``pserve`` command.

Update your application

Now, we'll update the application slightly to demonstrate the use of a simple Pyramid view bound to a mako template to serve a very basic OpenLayers application.

Because this application will use JSTools to insert script tags in debug mode, you have to add it as a dependency to your application. So edit your, and append 'JSTools' to the install_requires property.

Note that JSTools is also used in the buildout to merge and minify all the javascript used in your application in a single file. The jsbuild configuration file available in jsbuild/app.cfg expects OpenLayers library to be available at papyrussample/static/lib/openlayers/, so for example, if your project is under Git vcs, you can do:

$ git submodule add papyrussample/static/lib/openlayers

Now, we'll update our development.ini and production.ini to configure mako templates directory and jsbuild stuff. We also need to templatize these files so that they can have variables substituted from the buildout. So first rename these files:

$ mv development.ini
$ mv production.ini

Then edit both and, and add the following lines to the [app:main] section:

mako.directories = papyrussample:templates
jsbuild_cfg = ${jsbuild:config}
jsbuild_root_dir = ${jsbuild:base-dir}

Now launch buildout to install JSTools and generate development.ini and production.ini with substituted variables:

$ ./buildout/bin/buildout

Then configure a mako renderer for .html files for your Pyramid application: edit papyrussample/ and add the following lines before the config.scan():

# bind the mako renderer to .html file extensions
config.add_renderer('.html', renderer_factory)

Don't forget to also include the import statement:

from pyramid.mako_templating import renderer_factory

Then edit the my_view Pyramid view in papyrussample/ so that it looks like:

@view_config(route_name='home', renderer='index.html')
def my_view(request):
    return {"debug": "debug" in request.params}

Now you can launch pserve again:

$ ./buildout/bin/pserve development.ini
Starting server in PID 3453.
serving on

Open again to see a simple OpenLayers map. You can also open this page in debug mode with to load javascript that has not been minified.

Go ahead and build your application

You're now ready to build your application. Here are some tips that may help.

You will likely need to use a postgresql/postgis database instead of the default SQLite one, based on the settings available in the buildout configs. So edit your and and edit the sqlalchemy.url property to look like:

sqlalchemy.url = postgresql://${dbuser}:${dbpassword}@${dbhost}:${dbport}/${db}

If you use an AuthTktAuthenticationPolicy, it is important to configure it with a unique secret for security reasons. Fortunately, you can easily use buildout to generate a custom authtkt secret. You just have to edit your and and add the following line to the [app:main] section:

authtkt_secret = ${authtkt_secret}

Then configure an AuthTktAuthenticationPolicy that way:

auth_policy = AuthTktAuthenticationPolicy(settings.get('authtkt_secret'))