doc/09_deployment.rst

   1 .. _using-gunicorn:
   2
   3 Deploying with Gunicorn
   4 =======================
   5
   6 Starting with OpenERP 6.1, the server and web addons are WSGI_ compliant. In
   7 particular, support for the Gunicorn_ HTTP server is available. For some
   8 background information and motivation, please read http://www.openerp.com/node/1106.
   9 To install Gunicorn, please refer to Gunicorn's website.
  10
  11 .. _Gunicorn: http://gunicorn.org/
  12 .. _WSGI: http://en.wikipedia.org/wiki/Web_Server_Gateway_Interface
  13
  14 Summary
  15 -------
  16
  17 Configuring and starting an OpenERP server with Gunicorn is straightfoward. The
  18 different sections below give more details but the following steps are all it
  19 takes::
  20
  21  1. Use a configuration file, passing it to ``gunicorn`` using the ``-c``
  22     option.
  23  2. Within the same configuration file, also configure OpenERP.
  24  3. Run ``gunicorn openerp:wsgi.core.application -c gunicorn.conf.py``.
  25
  26 Sample configuration file
  27 -------------------------
  28
  29 A sample ``gunicorn.conf.py`` configuration file for Gunicorn can be found in
  30 the OpenERP server source tree. It is fairly well commented and easily
  31 customizable for your own usage. While reading the remaining of this page, it
  32 is advised you take a look at the sample ``gunicorn.conf.py`` file as it makes
  33 things easier to follow.
  34
  35 Configuration
  36 -------------
  37
  38 Gunicorn can be configured by a configuration file and/or command-line
  39 arguments. For a list of available options, you can refer to the official
  40 Gunicorn documentation http://gunicorn.org/configure.html.
  41
  42 When the OpenERP server is started on its own, by using the ``openerp-server``
  43 script, it can also be configured by a configuration file or its command-line
  44 arguments. But when it is run via Gunicorn, it is no longer the case. Instead,
  45 as the Gunicorn configuration file is a full-fledged Python file, we can
  46 ``import openerp`` in it and configure directly the server.
  47
  48 The principle can be summarized with this three lines (although they are spread
  49 across the whole sample ``gunicorn.conf.py`` file)::
  50
  51   import openerp
  52   conf = openerp.tools.config
  53   conf['addons_path'] = '/home/openerp/addons/trunk,/home/openerp/web/trunk/addons'
  54
  55 The above three lines first import the ``openerp`` library (i.e. the one
  56 containing the OpenERP server implementation). The second one is really to
  57 shorten repeated usage of the same variable. The third one sets a parameter, in
  58 this case the equivalent of the ``--addons-path`` command-line option.
  59
  60 Finally, Gunicorn offers a few hooks so we can call our own code at some points
  61 in its execution. The most important one is the ``on_starting`` hook. It lets
  62 us properly initialize the ``openerp`` library before Gunicorn starts handling
  63 requests. ``pre_request`` and ``post_request`` are called before and after
  64 requests are handled. We provide functions in ``openerp.wsgi.core`` that can be
  65 used to define those hooks: a typical Gunicorn configuration for OpenERP will
  66 thus contains::
  67
  68   on_starting = openerp.wsgi.core.on_starting
  69   pre_request = openerp.wsgi.core.pre_request
  70   post_request = openerp.wsgi.core.post_request
  71
  72 Running
  73 -------
  74
  75 Once a proper configuration file is available, running the OpenERP server with
  76 Gunicorn can be done with the following command::
  77
  78   > gunicorn openerp:wsgi.core.application -c gunicorn.conf.py
  79
  80 ``openerp`` must be importable by Python. The simplest way is to run the above
  81 command from the server source directory (i.e. the directory containing the
  82 ``openerp`` module). Alternatively, the module can be installed on your machine
  83 as a regular Python library or added to your ``PYTHONPATH``.
  84
  85 Running behind a reverse proxy
  86 ------------------------------
  87
  88 If you intend to run Gunicorn behind a reverse proxy (nginx_ is recommended),
  89 an alternative entry point is available in ``openerp.wsgi.proxied``. That entry
  90 point uses werkzeug's ProxyFix_ class to set a few headers. You first have to
  91 explicitely import that sub-module if you want to use it. So add this line in
  92 the configuration file::
  93
  94   import openerp.wsgi.proxied
  95
  96 and then adapt the command-line::
  97
  98   > gunicorn openerp:wsgi.proxied.application -c gunicorn.conf.py
  99
 100 .. _nginx: http://nginx.org/en/
 101 .. _ProxyFix: http://werkzeug.pocoo.org/docs/contrib/fixers/#werkzeug.contrib.fixers.ProxyFix