Configuration Files
+++++++++++++++++++

Pylons comes with two main ways to configure an application::

    * Through the application's ``config`` directory
    * Through a user configuration file
    
Typically as a developer writing a Pylons application you will change the files in the ``config`` directory to change certain aspects of how your application behaves but any options you want the webmaster using your configuration file to be able to configure will be specified by the in a configuration file. This document describes how to use the webmaster configurable configuration file support in Pylons.

Default Configuration File Setup
================================

When you create a project using ``paster create --template=pylons`` a sample configuration file called ``development.ini`` is automatically produced as one of the project files. This is an example of a configuration file and contains sensible options for development use in your project. For example when you are developing a Pylons application it is very useful to be able to see a debug report every time an error occurs so the development.ini file includes options to enable debug mode so these errors are shown.

You can serve your application using this development configuration like this::

    paster serve --reload development.ini
    
The ``--reload`` option is useful during development as the server will automatically reload each time a file is changed so that you can test the changes without having to manually restart the server.
    
Say your application is called wiki, when a user comes to want to setup an application they will run the command::

    paster make-config wiki production.ini
    
This command produces a different configuration file with sensible options for production use. In particular, the debug display is disables as the report might contain your usernames, passwords or other information you wouldn't want end users to see.

You can find out how to control what is produced by the ``paster make-config`` by reading `Application Setup <application_setup>`_.

It is your responsibility as a developer to ensure that a sensible set of default configuration values exist when the webmaster uses the ``paster make-config`` command.

You can create as many different configuration files as you like. Typically a developer might have a ``development.ini`` configuration file for testing, a ``production.ini`` file produced by the ``paster make-config`` command for testing the command produces sensible production output. You might also want a ``testing.ini`` configuration for doing some specific testing or any other number of configurations appropriate for your application. You can deploy your configuration in a variety of ways supported by paste deploy but typically you would serve your configuration like this::

    paster serve production.ini
    
Configuration File Format
=========================

Configuration file format is described in great detail in the `Paste Deploy documentation <http://www.pythonpaste.org>`_.

Error Handling Options
======================

A number of error handling options can be specified in the config file. These are described in the `Error Handler <interactive_debugger.txt>`_ documentation but the important point to remember is that debug should always be set to ``false`` in production environments otherwise if an error occurs the visitor will be presented with the developer's interactive traceback which they could use to execute malicious code.

Getting Information From Configuration Files
============================================

All information from your configuration file is available in the ``paste.config`` key of ``environ``. It can be obtained like this:

.. code-block:: Python
    
    config = request.environ['paste.config']
    
There is also a handy shortcut for when the ``request`` variable isn't in scope:

.. code-block:: Python
    
    from paste.deploy import CONFIG
    config = CONFIG

Either way, the ``config`` object returned is the same. It behaves like a dictionary and has two keys, ``app`` which contains config keys in the ``[app:main]`` section of the config file and ``default`` which contains the global configuration settings from the ``[DEFAULT]`` section. 

For example you can obtain the location of the cache directory like this:

.. code-block:: Python

    cache_dir = config['app_conf'].get('cache_data_dir')
    
Or the name of the package like this:

.. code-block:: Python

    package = config['app_conf'].get('package')
    
Or the debug status like this:

.. code-block:: Python
    
    from paste.deploy.converters import asbool
    debug = asbool(config['app_conf'].get('debug'))

PrefixMiddleware
================

``PrefixMiddleware`` provides a way to manually override the root prefix (``SCRIPT_NAME``) of your application for certain, rare situations.

When running an application under a prefix (such as '``/james``') in FastCGI/apache, the ``SCRIPT_NAME`` environment variable is automatically set to to the appropriate value: '``/james``'. Pylons' URL generating functions, such as ``url_for``, always take the ``SCRIPT_NAME`` value into account.

One situation where ``PrefixMiddleware`` is required is when an  application is accessed via a reverse proxy with a prefix. The application is accessed through the reverse proxy via the the URL prefix '``/james``', whereas the reverse proxy forwards those requests to the application at the prefix '``/``'.

The reverse proxy, being an entirely separate web server, has no way of specifying the ``SCRIPT_NAME`` variable; it must be manually set by a ``PrefixMiddleware`` instance. Without setting ``SCRIPT_NAME``, ``url_for`` will generate URLs such as: '``/purchase_orders/1``', when it should be generating: '``/james/purchase_orders/1``'.

To filter your application through a ``PrefixMiddleware`` instance, add the following to the '``[app:main]``' section of your .ini file:

.. code-block:: PasteIni

    filter-with = proxy-prefix

    [filter:proxy-prefix]
    use = egg:PasteDeploy#prefix
    prefix = /james

The name ``proxy-prefix`` simply acts as an identifier of the filter section; feel free to rename it.

These .ini settings are equivalent to adding the following to the end of your application's ``config/middleware.py``, right before the ``return app`` line:

.. code-block:: Python

    # @@@ This app is served behind a proxy via the following prefix (SCRIPT_NAME) @@@
    app = PrefixMiddleware(app, global_conf, prefix='/james')

Whereas the modification to ``config/middleware.py`` will setup an instance of ``PrefixMiddleware`` under every environment (.ini).
