Serving Static Files

Using the Static Filter

When you quickstart a TurboGears project, there are several static filters already set up for you in your application's configuration in <yourpackage>/config/app.cfg:

• All URLs below "/static" are served from files below the directory <yourproject>/<yourpackage>/static/.
• The URL "/favicon.ico" is served from the file <yourproject>/<yourpackage>/static/images/favicon.ico.

In a quickstarted project, the static directory also contains the three sub-directories css, images, and javascript. If, for example, you put a CSS stylesheet file named mystyles.css in the css directory, it can be accessed by the URL "/static/css/mystyles.css".

Let's look at the static filter configuration in detail:

[/static]
static_filter.on = True
static_filter.dir = "%(top_level_dir)s/static"

[/favicon.ico]
static_filter.on = True
static_filter.file = "%(top_level_dir)s/static/images/favicon.ico"

The string in square brackets [] denotes the preferred web url. For example, the first entry [/static] allows us to access static files at http://localhost:8080/static.

static_filter.on = True

The second line "static_filter.on = True" is necessary for all static filter sections.

static_filter.dir = "%(top_level_dir)s/static"

You can use "static_filter.file" or "static_filter.dir" to locate the directory or file. You can also use a regular expression with "static_filter.match".

The static_filter requires all paths to be absolute. You can use "%(top_level_dir)s" to denote the "top level directory" of this project.

For example, to publish a file that is in the the top level directory of your project use something like:

[/sitemap.xml]
static_filter.on = True
static_filter.file = "%(top_level_dir)s/sitemap.xml"

You can also specify what content-type to set depending on the extension of each file being served (e.g. rss file as [/rss], atom files as [/atom]).

[/rss]
static_filter.on = True
static_filter.content_types = {'rss': 'application/rss+xml'}
static_filter.dir = '/full/path/to/feed'

[/atom]
static_filter.on = True
static_filter.content_types = {'atom': 'application/atom+xml'}
static_filter.dir = '/full/path/to/feed'

Using the serveFile() Function

You might want to have a particular way to serve static content that cannot be achieved via the static filter. In such cases, use the serveFile function in your exposed method instead.

from cherrypy.lib.cptools import serveFile
return serveFile("/path/to/file")

serveFile() lets us have more flexibility to control the access of files.

For more information, refer to the CherryPy documentation about Serving static content.

Apache (and Other Web Servers) Setup

For more information about serving static files with a web server instead of the CherryPy application server, please refer to these docs:

• BehindApache
• LightTPD
• NginxIntegration