This document will show you how to get started playing around with Deliverance quickly. This quickstart is written for a Linux, Mac, or BSD-using audience. Sorry Windows users.
If you are familiar with virtualenv and easy_install you can skip this section.
We’ll be setting everything up in an isolated environment. Nothing in this will effect anything on your system outside of the directories we set up in this tutorial – so you can just delete the directory and forget about the whole thing if you don’t like it.
The first thing we’ll do is get virtualenv and create an environment. Grab virtualenv.py, and run:
$ python virtualenv.py --no-site-packages DelivTest
This will create an environment in DelivTest/ and install easy_install. There’s also a new Python interpreter in DelivTest/bin/python – anything in DelivTest/bin/ will be tied to this environment. It’ll use libraries from the environment and install libraries into the environment.
Note you can run source DelivTest/bin/activate to change $PATH so that everytime you run python, easy_install, etc., you’ll be running it from the environment you’ve created.
We won’t actually use easy_install much, we’ll just install another installer:
$ DelivTest/bin/easy_install pip
And we’ll use the pip installer to install Deliverance. This has the benefit over easy_install of installing all the source at once and with versions of the software that are known to work with each other. So, we’ll install the Deliverance bundle:
$ DelivTest/bin/pip install http://deliverance.openplans.org/dist/Deliverance-snapshot-latest.pybundle
This can take a long time to crunch. On a Mac you must have the developer tools installed.
For some people on some machines, you may find that the normal installation fails. Or you might just like buildout. If you do, here’s an example of a buildout.cfg file for building Deliverance (from Martin Aspeli):
[buildout] parts = lxml server develop = src/Deliverance versions = versions [versions] lxml = 2.1.2 [lxml] recipe = z3c.recipe.staticlxml egg = lxml == 2.1.2 force = false [server] recipe = zc.recipe.egg eggs = lxml PasteScript Deliverance interpreter = py
We have the software installed, but not the configuration to run it. To create the configuration run:
$ DelivTest/bin/paster create -t deliverance DelivTest Selected and implied templates: deliverance#deliverance Basic template for a deliverance-proxy setup Variables: egg: TestEnv package: testenv project: TestEnv Enter host (The host/port to serve on) ['localhost:8000']: Enter proxy_url (The main site to connect/proxy to) ['http://localhost:8080']: Enter proxy_rewrite_links (Rewrite links from sub_host?) ['n']: Enter password (The password for the deliverance admin console) ['']: test Enter theme_url (A URL to pull the initial theme from (optional)) ['']: http://mysite.com Creating template deliverance ...
It will ask you about some questions:
Once you’ve entered these values, it will set up a basic layout with a file etc/deliverance.xml for the configuration, and the theme in theme/theme.html.
You can start the server with:
$ ./bin/deliverance-proxy ./etc/deliverance.xml
The site will be at http://localhost:8000 and you can login at http://localhost:8000/.deliverance/login
Once you have logged in you can look at http://localhost:8000/?deliv_log to see a log of everything Deliverance is doing (at the bottom of the page).
Gaël Pasgrimaud wrote up instructions on installing Deliverance using buildout and pip. The basic recipe looks like:
[buildout] # the cache dir is used by buildout & pip download-cache = download parts = eggs [eggs] recipe = gp.recipe.pip # eggs installed by pip (also add the Deliverance bundle) install = Cython --install-option=--static-deps lxml==2.2alpha1 http://deliverance.openplans.org/dist/Deliverance-snapshot-latest.pybundle # eggs installed by zc.recipe.egg eggs = Paste pyquery
This uses his gp.recipe.pip buildout recipe.
Here’s where the quickstart ends for now; you’ll have to read the rest of the documentation to understand the rules, specifically the rule and theme section.