plone.recipe.varnish 1.0rc4

Buildout recipe to install varnish

plone.recipe.varnish is a zc.buildout recipe to install Varnish. Even though the name contains the name Plone, there is nothing Plone specific about this recipe: it works for non-Zope sites just as well.

Configuring it is very simple. For example:

[myvarnish]
recipe = plone.recipe.varnish:instance
bind = 127.0.0.1:8000
backends = 127.0.0.1:8080
cache-size = 1G

[varnish-build]
recipe = plone.recipe.varnish:build
url = http://puzzle.dl.sourceforge.net/sourceforge/varnish/varnish-1.1.2.tar.gz

This configures two buildout parts: varnish-build which will download, compile and install varnish and myvarnish which runs Varnish, configured to listen on 127.0.0.1:8000 for requests, using a 1 gigabyte cache and sending requests to a backend at 127.0.0.1:8080.

Wrappers for all the varnish commands are created in the bin directory of your buildout.

Virtual hosting

Varnish supports virtual hosting by selecting a different backend server based on headers on the incoming request. You can configure the backends through the backends option:

[myvarnish]
backends =
   plone.org:127.0.0.1:8000
   plone.net:127.0.0.1:9000

This will generate a configuration which sends all traffic for the plone.org host to a backend server running on port 8000 while all traffic for the plone.net host is send to port 9000.

Zope 2 hosting

If you are using Zope 2 as backend server you will need to rewrite the URL so the Zope Virtual Host Monster can generate correct links for links in your pages. This can be done either by a web server such as Apache or nginx but can also be done by Varnish. This can be configured using the zope_vhm_map option. Here is an example:

[myvarnish]
zope2_vhm_map =
    plone.org:/plone
    plone.net:/plone

This tells us that the domain plone.org should be mapped to the location /plone in the backend. By combing this with the information from the backends option a varnish configuration will be generated that maps URLs correctly.

plone.recipe.varnish:build reference

The plone.recipe.varnish:build recipe takes care of downloading Varnish, compiling it on your system and installing it in your buildout.

If you are running on an OS/X system a patch to fix a linking error will be automatically applied. More information on the bug and patch can be found at http://varnish.projects.linpro.no/ticket/118 .

It can be configured with any of these options:

url

URL for an archive containing the Varnish sources. Either url or svn has to be specified.

svn

URL for a subversion repository containing Varnish sources. Either url or svn has to be specified.

Please note that the configuration generated by this recipe requires Varnish 1.1.1 or later.

plone.recipe.varnish:instance reference

The plone.recipe.varnish:instance recipe create a Varnish configuration file and creates a wrapper script inside your buildout that will start Varnish with the correct configuration.

Please note that the configuration generated by this recipe requires Varnish 1.1.1 or later.

It can be configured with any of these options:

daemon

The path of the varnish daemon to use. Defaults to bin/varnishd inside your buildout, which is the executable created by the plone.recipe.varnish:build recipe.

mode

Specify whether the varnish daemon should run in ‘daemon’ or ‘foreground’ mode. The latter is useful when varnish is run by service supervision tools like daemontools or runit. Defaults to ‘daemon’.

cache-size

The size of the cache.

bind

Hostname and port on which Varnish will listen for requests. Defaults to 127.0.0.1:8000.

config

Path for a Varnish VCL configuration to use. If you use this option you can not use the backends or zope_vhm_map options.

backends

Specifies the backend or backends which will process the (uncached) requests. There are two ways to specify backends: using hostname:backend server:backend port or backend server:backend port. Using the first option allows you to do virtual hosting. If multiple backends are specified you have to use the full form including the (virtual) hostname. Defaults to 127.0.0.1:8080.

zope_vhm_map

Defines a virtual host mapping for Zope servers. This is a list of hostname:ZODB location entries which specify the location inside Zope where the website for a virtual host lives.

telnet

If specified sets the hostname and port on which Varnish will listen for commands using its telnet interface.

user

The name of the user varnish should switch to before accepting any requests. Defaults to nobody.

group

The name of the group varnish should switch to before accepting any request. This defaults to the main group for the specified user.