root/branches/cherrypy-2.x/docs/book/xml/configsystemoverview.xml

<?xml version="1.0" encoding="UTF-8"?>
<section xmlns:db="http://docbook.org/docbook-ng" xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xml:id="configsystemoverview">
    <title>Configuration system</title>
    <para>The CherryPy configuration system provides fine-grained control over how each part of the
    application should react. You will use it for two reasons:</para>
    <itemizedlist>
        <listitem>
            <para>Web server settings</para>
        </listitem>
        <listitem>
            <para>Enabling filters per path</para>
        </listitem>
    </itemizedlist>
    <para>You will be able to declare the configuration settings either from a file or from a Python
    dictionary.</para>
    <para>First of all, let's see how a typical configuration file is defined.</para>
    <example>
        <title>Configuration file</title>
        <programlisting linenumbering="numbered">
            # The configuration file called myconfigfile.conf
            [global]
            server.socket_port=8080
            server.socket_host=""
            server.socket_file=""
            server.socket_queue_size=5
            server.protocol_version="HTTP/1.0"
            server.log_to_screen=True
            server.log_file=""
            server.reverse_dns=False
            server.thread_pool=10
            server.environment="development"
            
            [/service/xmlrpc]
            xmlrpc_filter.on = True
            
            [/admin]
            session_authenticate_filter.on=True
            
            [/css/default.css]
            static_filter.on = True
            static_filter.file = "data/css/default.css"
            
            # From your script...
            cherrypy.config.update(file="myconfigfile.conf") 
        </programlisting>
    </example>
    <para>The settings can also be defined using a python dictionary instead of a file as
    follows:</para>
    <example>
        <title>Configuration dictionary</title>
        <programlisting linenumbering="numbered">
      settings = { 
         'global': {
            'server.socket_port' : 8080,
            'server.socket_host': "",
            'server.socket_file': "",
            'server.socket_queue_size': 5,
            'server.protocol_version': "HTTP/1.0",
            'server.log_to_screen': True,
            'server.log_file': "",
            'server.reverse_dns': False,
            'server.thread_pool': 10,
            'server.environment': "development"
         },
         '/service/xmlrpc' : {
            'xmlrpc_filter.on': True
         },
         '/admin': {
            'session_authenticate_filter.on' :True
         },
         '/css/default.css': {
            'static_filter.on': True,
            'static_filter.file': "data/css/default.css"
         }
      }
      cherrypy.config.update(settings)
        </programlisting>
    </example>
    <section>
        <title>Configuration Sections</title>
        <para>Each section of the configuration refers to an object path; the object path is used to
        lookup the correct handler for each Request-URI. Therefore when the server receives a
        Request-URI of <code>/css/default.css</code>, the static filter will handle the request, and
        the server will actually return the physical file at
        <filename>data/css/default.css</filename>. Since the path <code>/service/xmlrpc</code> has
        the XML-RPC filter enabled, all the exposed methods of the object
        <code>cherrypy.root.service.xmlrpc</code> will be treated as XML-RPC methods.</para>
        <para>The <code>global</code> entry represents settings which apply outside the request
        process, including server settings such as the port, the protocol version to use by default,
        the number of threads to start with the server, etc. This is <emphasis>not</emphasis> the
        same as the root entry <code>[/]</code>, which maps to cherrypy.root.</para>
        <para>By default, URI's and object paths are equivalent; however, filters may rewrite the
        objectPath to produce a different mapping between URI's and handlers. This is necessary, for
        example, when mounting applications at virtual roots (e.g. serving the object path
        <code>/welcome</code> at the URI "/users/~rdelon/welcome").</para>
    </section>
    <section>
        <title>Configuration Entries</title>
        <para>All values in the configuration file must be valid Python values. Strings must be
        quoted, booleans must be True or False, etc.</para>
        <section>
            <title>server.environment</title>
            <para>The <code>server.environment</code> entry controls how CherryPy should run. Three
            values are built in:</para>
            <itemizedlist>
                <listitem>
                    <para>development</para>
                    <itemizedlist>
                        <listitem>
                            <para>log_debug_info_filter is enabled</para>
                        </listitem>
                        <listitem>
                            <para>HTTPErrors (and therefore the default _cp_on_error) display
                            tracebacks in the browser if errors occur</para>
                        </listitem>
                        <listitem>
                            <para>autoreload is enabled</para>
                        </listitem>
                        <listitem>
                            <para>NotFound errors (404) are listed in the error.log</para>
                        </listitem>
                    </itemizedlist>
                </listitem>
                <listitem>
                    <para>production</para>
                    <itemizedlist>
                        <listitem>
                            <para>log_debug_info_filter is disabled</para>
                        </listitem>
                        <listitem>
                            <para>tracebacks are logged, but are not displayed in the browser</para>
                        </listitem>
                        <listitem>
                            <para>autoreload is disabled</para>
                        </listitem>
                        <listitem>
                            <para>NotFound errors (404) aren't listed in the error log</para>
                        </listitem>
                    </itemizedlist>
                </listitem>
                <listitem>
                    <para>staging (same as production for the moment)</para>
                </listitem>
            </itemizedlist>
            <para>Beginning in CherryPy 2.2, the behavior of each environment is defined in
            <code>cherrypy.config.environments</code>, a dict whose keys are "development",
            "production", etc, and whose values are dicts of config keys and values. Application
            developers are free to modify existing environments, or define new environments for use
            by their deployers, by modifying this container. For example, if you develop an
            application which absolutely cannot handle autoreload, your app can set
            <code>cherrypy.config.environments['development']['autoreload.on'] = False</code>.
            Deployers who selected the "development" environment would then be free from the danger
            of autoreload interacting with your application. Another example of using
            config.environments directly might be an application which needs a "development" and
            "production" environment, but also separate "beta", "rc", "live data" and/or "testing"
            environments.</para>
        </section>
    </section>
</section>