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 start with the ``#`` character.

[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)
                                                   - ``fapws3``: fast event-driven HTTP server
                                                     (experimental)
                                                   - ``eventlet``: fast event-driven 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
                              dependent*         value is explicitly given, the ``standalone``,
                                                 ``fapws3`` 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.
debug               No        off                Put the publisher in debug mode
=================== ========= ================== ==================================================

If the application is publisher by the FastCGI publisher (i.e
``type=fastcgi``), these parameters can also be set:

=================== ========= ================== ==================================================
Name                Mandatory Default value      Description
=================== ========= ================== ==================================================
socket              No        *No default value* Unix socket path instead of the TCP host:port
                                                 socket
umask               No        *No default value* Unix permission mask of the unix socket to create
minSpare            No        1                  Minimum number of processes ready to process new
                                                 requests
maxChildren         No        50                 Maximum number of running processes
maxSpare            No        5                  Maximum number of idle processes
maxRequest          No        *No default value* Maximum number of requests served by a process
                                                 before being killed
=================== ========= ================== ==================================================

.. note::

   New publishers can be added to the framework, and then selected with the ``type``
   parameter, by registering them under the ``[nagare.publishers]`` :doc:`entry point <entry_points>`.

[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 ``standalone``,
                                                     ``fapws3`` 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 configured:

=================== ========= ================== ==================================================
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 configured:

=================== ========= ================== ==================================================
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) does 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]``
   :doc:`entry point <entry_points>`.

[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
=================== ========= ================== ==================================================

