The publisher configuration file
================================


Using the configuration file
----------------------------

To configure how an application is published, use the ``-c`` option of the
``serve`` administrative command:

  .. code-block:: sh

    <NAGARE_HOME>/bin/nagare-admin serve -c /path/to/the/publisher/config.cfg <application>

Several examples of publisher configurations are located into ``conf/publishers``
under the framework installation directory.

Structure
---------

For the boolean parameters, a value of ``true``, ``yes``, ``on`` or ``1`` means True
and a value of ``false``, ``no``, ``off`` or ``0`` mean False.

Comments, starting with the ``#`` character can be added to a configuration file.

[publisher] section
~~~~~~~~~~~~~~~~~~~

This section defines the publisher to use.

=================== ========= ================== ================================================
Name                Mandatory Default value      Description
=================== ========= ================== ================================================
type                No        standalone         Choice of the publisher to use.

                                                 The current choices are:

                                                   - ``standalone``: Python threaded HTTP server
                                                     (convenient in development mode)
                                                   - ``fastcgi``: multi-processes fastcgi server.
                                                     A external HTTP is required (recommended in production)
                                                   - ``fapws2``: fast events drivent HTTP server (experimental)
                                                   - ``eventlet``: fast events drivent HTTP server (experimental)
host                No        127.0.0.1          By default, the publisher only accepts requests
                                                 on the local interface. If you want to accept
                                                 external requests, set this parameter to the
                                                 internet address of your external interface or
                                                 to '0.0.0.0' to listen to on all the interfaces
                                                 of your system.
                                                 The optional ``--host`` on the command line
                                                 takes precedence over this parameter.
port                No        *publisher         Port where to listen to the requests. If no
                              dependante*        value is explicitly given, the ``standalone``,
                                                 ``fapws2`` and ``eventlet`` publishers listen on
                                                 port ``8080``. And the ``fastcgi`` publisher
                                                 listen on ``9000``.
                                                 The optional ``--port / -p`` on the command line
                                                 takes precedence over this parameter.
=================== ========= ================== ================================================

All other parameters, if present, are passed as keywords to the SQLALchemy
``create_engine()`` call (see http://www.sqlalchemy.org/docs/core/engines.html#engine-creation-api)

.. note::

   New publishers can be added to the framework, and then selected with the ``type``
   parameter, by registering them under the ``[nagare.publishers]`` entry point
   (see :wiki:`EntryPoints`).

[sessions] section
~~~~~~~~~~~~~~~~~~

This section defined the sessions manager to use.

=================== ========= ================== ================================================
Name                Mandatory Default value      Description
=================== ========= ================== ================================================
type                No        standalone         Choice of the sessions manager to use.

                                                 The current choices are:

                                                   - ``standalone``: threads-safe in-memory sessions
                                                     manager. Can be used with the ``standalon``,
                                                     ``fapws2`` or ``eventlet`` publisher.
                                                   - ``memcache``: the sessions are stored and
                                                     shared into an external memcached server.
                                                     Can be use will all the publishers
=================== ========= ================== ================================================

If the ``type`` parameter has the value ``standalone``, the following parameters
can be configurated:

=================== ========= ================== ================================================
Name                Mandatory Default value      Description
=================== ========= ================== ================================================
nb                  No        10000              Maximum number of sessions keeped
=================== ========= ================== ================================================

If the ``type`` parameter has the value ``memcache``, the following parameters
can be configurated:

=================== ========= ================== ================================================
Name                Mandatory Default value      Description
=================== ========= ================== ================================================
host                No        127.0.0.1          Address of the memcached server
port                No        11211              Port of the memcached server
ttl                 No        0                  How long (in seconds), do the session live ?
                                                 A value of ``0`` means the sessions are managed
                                                 in LRU.
reset               No        on                 If this parameter is true, then all the sessions
                                                 are removed from the memcached server when the
                                                 application (re)starts.
debug               No        off                Display the requests sent to the memcached server
=================== ========= ================== ================================================

.. note::

   New sessions managers can be added to the framework, and then selected with the
   ``type`` parameter, by registering them under the ``[nagare.sessions]`` entry point
   (see :wiki:`EntryPoints`).

[reloader] section
~~~~~~~~~~~~~~~~~~

This section configures the reloader process which automatically detect source
changes and relaunch the application.

=================== ========= ================== ================================================
Name                Mandatory Default value      Description
=================== ========= ================== ================================================
activated           No        off                If not activated, the framework will not read
                                                 the following parameters.
                                                 In production, don't activate the reloader.
interval            No        1                  Time, in seconds, between the control of
                                                 source changes
=================== ========= ================== ================================================

.. wikiname: PublisherConfiguration
