2. Administrator reference

2.1. Install a CherryPy application

2.2. Config options reference

2.2.1. List of core (ie: not for filters) config options:

  • [global] server.socket_port: port number where the server is listening (defaults to 8080)

  • [global] server.log_file: path to a file to log CherryPy server activity. Items logged include startup config info, tracebacks and HTTP requests. It is disabled by default and everything is logged to the screen.

  • [global] server.log_access_file: path to a file where access log data will be stored in Common Log Format. The default is to write access log data to the screen. If a file is specified, the access log data is no longer written to the screen.

  • [global] server.log_to_screen: controls whether any log data is written to the screen. It defaults to on (True). For performance reasons, it is best to have this option turned off on a production server.

  • [global] server.log_tracebacks: controls whether or not tracebacks are written to the log (screen or otherwise). Defaults to on (True) If set to False, only a 500 return code will be logged in the access log.

  • [global] server.max_request_header_size: maximum acceptable size of a request header, in bytes (defaults to 500KB). If a longer request arrives, the server will interrupt it and return a 413 error. This setting is global (ie: doesn't depend on the path). Set it to zero to remove the limit

  • [global] server.default_content_type: default content type to be used for all responses (default to text/html). This setting is global (ie: doesn't depend on the path).

  • [/path] server.max_request_body_size: maximum acceptable size of a request body, in bytes (defaults to 100MB). If a longer request body arrives, the server will interrupt it and return a 413 error. This setting can be configured per path. This is useful to limit the size of uploaded files. Set it to zero to remove the limit

  • TODO: other config options

2.3. Mounting applications

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 cherrypy.root tree, and of config file paths.

Beginning in version 2.2, CherryPy provides a tool to make mounting applications easier: cherrypy.tree.mount(app_root, baseurl=None, conf=None). 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:

Example 3.12. 

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'}
                       })

...you can now write the last two lines like this:

Example 3.13. 

cherrypy.tree.mount(Root(), "/path/to/approot",
                    {'/': {'server.log_file': '/var/log/myapp.log'}})

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.

You can read more about the cherrypy.tree object in the API Reference later in this book.

2.4. Production Setup

2.4.1. Quick overview

2.4.2. Servers

2.4.2.1. Built in server
2.4.2.2. Behind Apache
2.4.2.3. Built in server
2.4.2.4. FastCGI
2.4.2.5. mod_python