OMERO.web deployment
====================

OMERO.web is the web application component of the OMERO platform which
allows for the management, visualization (in a fully multi-dimensional
image viewer) and annotation of images from a web browser. It also
includes OMERO.webadmin for managing users and groups.


OMERO.web is an integral part of the OMERO platform and can be deployed
with:

-  FastCGI using a FastCGI capable web server such as
   `Apache 2.2 <http://httpd.apache.org/>`_ (with
   `mod\_fastcgi <http://www.fastcgi.com/drupal/>`_ enabled),
   `Apache 2.4+ <http://httpd.apache.org/>`_ (with the bundled
   `mod\_proxy\_fcgi` enabled),
   `nginx <http://nginx.org/>`_ or
   `lighttpd <http://www.lighttpd.net/>`_ (since OMERO 4.2.1)
-  The built-in Django lightweight development server (for **testing**
   only; see the :doc:`/developers/Web/Deployment` page)

You can find more information about FastCGI and where to get modules or
packages for your distribution on the
`FastCGI website <http://www.fastcgi.com/drupal/node/3>`_.

If you need help configuring your firewall rules, see the :doc:`/sysadmins/server-security` page.

Prerequisites
-------------

-  OMERO and its prerequisites (see :doc:`server-installation`).

-  Python 2 (2.6 or later)

   -  `Pillow`_ should be available for your distribution

   -  Matplotlib_ should be available for your distribution

-  A FastCGI capable web server

Quick Start
-----------

.. _fastcgi_configuration:

FastCGI Configuration (Unix/Linux)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you have installed Nginx or Apache OMERO can automatically generate a
configuration file for your web server, see :ref:`apache22_configuration`,
:ref:`apache24_configuration` or :ref:`nginx_configuration`.
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.


.. _apache22_configuration:

Apache 2.2 configuration (mod_fastcgi)
""""""""""""""""""""""""""""""""""""""

Install `mod\_fastcgi <http://www.fastcgi.com/drupal/>`_.
To create a site configuration file for inclusion in the main Apache
configuration redirect the output of the following command into a file:

::

    $ bin/omero web config apache

.. literalinclude:: apache-omero.conf
   :lines: 55-

.. note::
    The default configuration file installed with `mod_fastcgi` may be
    incompatible with OMERO. In particular, the `FastCGIWrapper` option
    conflicts with `FastCGIExternalServer` required by OMERO and must be
    removed or commented out.

.. note::
    To configure an HTTPS server follow
    `the Apache documentation <http://httpd.apache.org/docs/trunk/mod/mod_ssl.html>`_.


.. _apache24_configuration:

Apache 2.4+ configuration (mod_proxy_fcgi)
""""""""""""""""""""""""""""""""""""""""""

The `mod\_proxy\_fcgi`, `mod\_proxy` and `mod\_rewrite` Apache modules should
already be installed and enabled as part of the Apache installation, if this
is not the case then enable them.
To create a site configuration file for inclusion in the main Apache
configuration redirect the output of the following command into a file:

::

    $ bin/omero web config apache-fcgi

.. literalinclude:: apache-fcgi-omero.conf
   :lines: 51-

.. _nginx_configuration:

Nginx configuration
"""""""""""""""""""

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::
    To configure an HTTPS server follow
    `the nginx documentation <http://nginx.org/en/docs/http/configuring_https_servers.html>`_.
    Make sure ``fastcgi_param HTTPS $https;`` is uncommented.

.. 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;
            ...
        }


Starting OMERO.web
~~~~~~~~~~~~~~~~~~

Start the Django FastCGI workers:

::

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

.. note::
    The Django FastCGI 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 FastCGI workers (PID 59217) killed.


Logging in to OMERO.web
-----------------------

Once you have deployed and started the server, you can use your browser
to access OMERO.webadmin or the OMERO.webclient:

-  **http://your\_host/omero** OR, for development server:
   **http://localhost:4080**

.. figure:: /images/installation-images/login.png
   :align: center
   :width: 55%
   :alt: OMERO.webadmin login

   OMERO.webadmin login

.. note::
	This starts the server in the foreground. It is your
	responsibility to place it in the background, if required, and
	manage its shutdown.


.. _unix_omero_web_maintenance:

OMERO.web Maintenance
---------------------

-  Session cookies :property:`omero.web.session_expire_at_browser_close`:

   -  A boolean that determines whether to expire the session when the user
      closes their browser.
      See :djangodoc:`Django Browser-length sessions vs. persistent
      sessions documentation <topics/http/sessions/#browser-length-vs-persistent-sessions>`
      for more details. Default: ``True``.

      ::

          $ bin/omero config set omero.web.session_expire_at_browser_close "True"

   -  The age of session cookies, in seconds. Default: ``86400``.

      ::

          $ bin/omero config set omero.web.session_cookie_age 86400

-  Session engine:

   -  Each session for a logged-in user in OMERO.web is kept in the session 
      store. Stale sessions can cause the store to grow with time. OMERO.web 
      uses by default the OS file system as the session store backend and 
      does not automatically purge stale sessions, see 
      :djangodoc:`Django file-based session documentation <topics/http/sessions/#using-file-based-sessions>`
      for more details. It is therefore the responsibility of the OMERO 
      administrator to purge the session cache using the provided management 
      command:

      ::

          $ bin/omero web clearsessions

      It is recommended to call this command on a regular basis, for example 
      as a :ref:`daily cron job<linux_walkthrough_regular_tasks>`, see
      :djangodoc:`Django clearing the session store documentation <topics/http/sessions/#clearing-the-session-store>`
      for more information.

      .. note::
          OMERO.web offers alternative session backends to automatically 
          delete stale data using the cache session store backend, see
          :djangodoc:`Django cached session documentation <topics/http/sessions/#using-cached-sessions>`
          for more details. After installing all the cache prerequisites set the following:

          ::

              $ bin/omero config set omero.web.caches '{"default": { "BACKEND": "django.core.cache.backends.memcached.MemcachedCache", "LOCATION": "127.0.0.1:11211", "TIMEOUT": "86400" } }'
              $ bin/omero config set omero.web.session_engine django.contrib.sessions.backends.cache

.. note::
    The generated Nginx and Apache configuration files will automatically
    display a maintenance page if an attempt is made to access OMERO.web whilst
    it is not running.


.. _customizing_your_omero_web_installation_unix:

Customizing your OMERO.web installation
---------------------------------------

By default OMERO.web expects to be run from the root URL of the web server.
This can be changed by setting :property:`omero.web.prefix` and
:property:`omero.web.static_url`. For example, to make OMERO.web appear at
`http://example.org/omero/`:

::

    $ bin/omero config set omero.web.prefix '/omero'
    $ bin/omero config set omero.web.static_url '/omero/static/'

and regenerate your web-server configuration
(see :ref:`fastcgi_configuration`).

The front-end webserver (Nginx, Apache) can be setup to run on a different
host from OMERO.web. You will need to set
:property:`omero.web.application_server.host` to ensure OMERO.web is
accessible on an external IP.

OMERO.web is configured to use FastCGI TCP by default. If you are using a
non-standard web server configuration and wish to use a file based socket
you can set :property:`omero.web.application_server` to `fastcgi`. This is a
highly specialized setup aimed at advanced users, so you will need to create
your own web server configuration file, and file socket with correct
permissions.

All configuration options can be found on various sections of
:ref:`web_index` developers documentation. For the full list, refer to
:ref:`web_configuration` properties or:

::

	$ bin/omero web -h 

The most popular configuration options include:

-  Debug mode, see :property:`omero.web.debug`.

-  Customize login page with your own logo, see
   :property:`omero.web.login_logo`.

-  Customizing index page, see :property:`omero.web.index_template`.

-  Enabling a public user see :doc:`/sysadmins/public`.