Quickstart

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.

Starting with virtualenv

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

Installing the Software

You can use easy_install to install the latest release of Deliverance and all its dependencies:

$ easy_install Deliverance

You can also install with pip if that’s your preference:

$ pip install Deliverance

This can take a long time to crunch, because of the lxml dependency. On a Mac you must have the developer tools installed.

Installing with buildout

If you prefer to use buildout, here’s an example of a buildout.cfg file for building Deliverance:

[buildout]
parts =
    server

[server]
recipe = zc.recipe.egg
eggs =
    PasteScript
    Deliverance

You might have trouble installing lxml, particularly if you’re on a Mac. If so, you might want to incorporate z3c.recipe.staticlxml into your buildout.

Warning: plone.recipe.deliverance

You might come across a package plone.recipe.deliverance. It is unmaintained, so don’t try to use it.

Creating a Configuration

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:

host:

The host that Deliverance will serve from. Note localhost (or 127.0.0.1) means that you can only connect from the machine itself. If you want it to be externally visible use 0.0.0.0.

proxy_host:

This is the location where all requests will go to. http://localhost:8080 is a common default for servers. You can also give a remote host and a path, like http://mysite.com/blog

proxy_rewrite_links:

If you are proxying to a site that doesn’t really expect you to be proxying to it, the links will probably be broken. You can give Y here to turn on link rewriting. It’s not 100% perfect (e.g., links put into Javascript), but it can be good for experimenting.

password:

The password to access the logging console. The username is always admin. You can add or update logins later.

theme_url:

If you want to base your theme on an existing page, you can give the URL of that page here. It will fetch that page and all the CSS and images from that page, so you can locally edit them. Otherwise an extremely simply theme will be setup.

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

Editing the Rules

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.