OMERO.web Nginx and Gunicorn deployment (Unix/Linux)
====================================================

.. _nginx_gunicorn_wsgi_configuration:

Nginx Gunicorn configuration (Unix/Linux)
-----------------------------------------

.. note:: Since OMERO 5.2, the OMERO web framework no longer bundles
      a copy of the Django package, instead manual installation of
      the Django dependency is required. It is highly recommended to use
      `Django 1.8`_ (LTS) which requires Python 2.7. For more information
      see :ref:`python-requirements` on the
      :doc:`/sysadmins/version-requirements` page.

Install `Django 1.8`_ and `Gunicorn <http://docs.gunicorn.org/>`_ using
package requirements file:

::

   $ pip install -r share/web/requirements-py27-nginx.txt


.. note:: For more details refer to
          :djangodoc:`how to install Django 1.8 <topics/install/#install-the-django-code>`
          or :djangodoc:`hot to upgrade Django to 1.8 <topics/install/#remove-any-old-versions-of-django>`.


If you have installed Nginx, OMERO can automatically generate a
configuration file for your web server. The location of the file
will depend on your system, please refer to your web server's manual.
See :ref:`customizing_your_omero_web_installation_unix`
for additional customization options.

Install `gunicorn <http://docs.gunicorn.org/>`_:

::

    $ pip install gunicorn

To create a site configuration file for inclusion in a system-wide nginx
configuration redirect the output of the following command into a file:

::

    $ bin/omero web config nginx

.. literalinclude:: nginx-omero.conf

.. note::
    OMERO.web requires ``body_in_file_only`` adjusted in your default nginx 
    config because nginx must buffer incoming data. Make sure you have that 
    set to the following config:

    ::

        http {
            ...
            sendfile on;
            send_timeout 60s;
            client_max_body_size 0;
            ...
        }

To configure an HTTPS server follow
`the nginx documentation <http://nginx.org/en/docs/http/configuring_https_servers.html>`_.

Start the Gunicorn worker processes running one thread listening on 127.0.0.1:4080:

::

    $ bin/omero web start
    ... static files copied to '/usr/local/dev/openmicroscopy/dist/lib/python/omeroweb/static'.
    Starting OMERO.web... [OK]

Additional settings can be configured from command line arguments:

.. program:: omero web start

.. option:: --workers WORKERS

    The number of worker processes for handling requests.

.. option:: --worker-connections WORKER_CONNECTIONS

    The maximum number of simultaneous clients.

.. option:: --wsgi-args WSGI_ARGS

    Additional arguments. For more details check
    `Gunicorn Documentation <http://docs.gunicorn.org/en/latest/settings.html>`_.


The Gunicorn workers are managed **separately** from other OMERO.server
processes. You can check their status or stop them using the
following commands:

::

    $ bin/omero web status
    OMERO.web status... [RUNNING] (PID 59217)
    $ bin/omero web stop
    Stopping OMERO.web... [OK]
    Django WSGI workers (PID 59217) killed.