TurboGears Configuration
TurboGears is designed to get running with a minimum of trouble and very little external configuration. For some applications, the only thing that will need to change from the basic "quickstart" configuration is the location of the database.
A quickstarted application comes with two config files: "dev.cfg" and "prod.cfg". The dev.cfg file is the one used while you're developing your application. prod.cfg contains appropriate settings for a "real" deployment, and can be passed in to your project's start script as a parameter.
CherryPy Configuration
TurboGears uses CherryPy's configuration system. The CherryPy site includes an overview of the configuration system and also includes a reference of some configuration options.
This document does not reproduce the basic CherryPy configuration options. It is a reference of TurboGears options.
TurboGears Configuration Reference
The [global] section of the config file is intended for settings that apply server-wide and at startup time. CherryPy also uses path-based config sections that are for setting filters and settings that apply only to one part of your site. For example,
note: tg.allow_json is new in 0.9
[/admin]
tg.allow_json = True
will set tg.allow_json only for the /admin part of the site.
Global Settings
- autoreload.package
- The autoreload functionality that comes with CherryPy reloads if any of the modules that have been imported change. This requires checking quite a few files and also is not compatible with zipped Egg files. TurboGears adds this config parameter to specify one package to watch for changes. For most applications this is adequate.
- server.webpath
- Specifies the root of the site for use when generating URLs.
Use this if your whole TurboGears instance is not at the root
of your webserver.
As of 0.9, this will also support incoming requests, eliminating the need for VirtualPathFilter.
- sqlobject.dburi
- The SQLObject URI that identifies the database to use for this application. The general form of the URI is databasetype://username:password@hostname:port/databasename. Note that for sqlite, the format is more like that of a file:// URL: sqlite:///absolute_path_to_file. Also note that on Windows systems, you use a | character instead of a : to refer to a drive letter. For example: sqlite:///d|databases/foo.db points to D:\databases\foo.db. ${nvlabel()} If you put notrans_ in front of the URI, the automatic database transactions will be turned off.
Note to MySQL users: If you use a different socket than /tmp/mysql.sock, you may specify which socket to use by adding a unix_socket argument to the dburi. i.e., mysql://user:pass@host:port/db?unix_socket=/path/to/mysql.sock
- tg.defaultview ${nvlabel()}
- Determines which template engine to use by default. If this is not set, Kid will be used to render the templates you specify in your controller. The template engine is identified by the file extension used.
- tg.mochikit_all ${nvlabel()}
- Whether or not to include MochiKit on all of your non-static pages. Defaults to False.
- tg.sitetemplate
- TurboGears applications that are intended to be reused should make sure that every page template ultimately extends sitetemplate. This config variable lets you set which template is used as the sitetemplate. The value should be of the form "packagename.templates.templatename", including the quotes.
Path-based Settings
- tg.allow_json ${nvlabel()}
- When this is set to False, calling a function with ?tg_format=json will not work by it's own. You need to set allow_json to True in the expose decorator or set the default format to json. Defaults to False.
- kid.outputformat
- Sets the default output format used when rendering Kid templates. By default, TurboGears will tell Kid to produce HTML files, which is optimum for most web applications. If your application needs to output XHTML or XML, you can set that here. There is more information about the available output methods.