root/branches/cherrypy-2.x/docs/book/xml/configureapplication.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="configureapplication">
    <title>Mounting applications</title>
    <para>So far, we have talked about applications as if they are always "mounted" at root; that is,
    that the URL "/" is the "base URL" for the application. However, this rarely happens in practice.
    Often, you not only have an application mounted at some other base URL, but it must coexist with
    other applications (perhaps in the same process). CherryPy has always allowed applications to be
    deployed simultaneously, but it was often a difficult process, and required a lot of manual
    manipulation of the <code>cherrypy.root</code> tree, and of config file paths.</para>
    <para> Beginning in version 2.2, CherryPy provides a tool to make mounting applications easier:
    <code>cherrypy.tree.mount(app_root, baseurl=None, conf=None)</code>. You pass it a handler tree,
    the base URL for the app, and a config dict or filename, and it does all of the "hard work" for
    you. For example, instead of writing this:</para>
    <example>
        <programlisting>import cherrypy

class Root:
    def index(self):
        return "Hello world! This is %s" % cherrypy.request.path
    index.exposed = True

cherrypy.root.path.to.approot = Root()
cherrypy.config.update({'/path/to/approot/': 
                           {'server.log_file': '/var/log/myapp.log'}
                       })</programlisting>
    </example>
    <para>...you can now write the last two lines like this:</para>
    <example>
        <programlisting>cherrypy.tree.mount(Root(), "/path/to/approot",
                    {'/': {'server.log_file': '/var/log/myapp.log'}})</programlisting>
    </example>
    <para>The call to mount() will prefix all of the config-section paths with your mount point path.
    If you use a config file instead of a Python dict, it becomes even cleaner.</para>
    <para>You can read more about the <code>cherrypy.tree</code> object in the API Reference later in
    this book.</para>
</section>