OMERO.web IIS deployment (Windows)
==================================

.. warning:: OMERO 5.2 is the last major version which will feature Windows
    support for OMERO.server and OMERO.web deployment. See
    `this blog post <http://blog.openmicroscopy.org/tech-issues/future-plans/deployment/2016/03/22/windows-support/>`_ for details. If you are installing a new server, we highly
    recommend you use a different OS (see
    :doc:`/sysadmins/version-requirements`).

.. _iis_configuration:

IIS configuration (Windows)
---------------------------

.. 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`_ on Windows. For more information
       see :ref:`python-requirements` on the
       :doc:`/sysadmins/version-requirements` page.

Install `Django 1.8`_ using package requirements file:

::

   C:\> pip install -r C:\OMERO.server\share\web\requirements-py27-win.txt

.. note:: For more details refer to `Django 1.8 installation on Windows <https://docs.djangoproject.com/en/1.8/howto/windows/>`_.

Install additional Python libraries:

Download the following whl files then run::

   set PYTHONPIP=C:\Python27\Scripts\pip.exe

   %PYTHONPIP% install matplotlib-1.4.3-cp27-none-win_amd64.whl
   %PYTHONPIP% install numpy-1.9.2+mkl-cp27-none-win_amd64.whl
   %PYTHONPIP% install numexpr-2.4.3-cp27-none-win_amd64.whl
   %PYTHONPIP% install Pillow-2.8.1-cp27-none-win_amd64.whl
   %PYTHONPIP% install pyparsing-2.0.3-py2-none-any.whl
   %PYTHONPIP% install python_dateutil-2.4.2-py2.py3-none-any.whl
   %PYTHONPIP% install pytz-2015.2-py2.py3-none-any.whl
   %PYTHONPIP% install six-1.9.0-py2.py3-none-any.whl
   %PYTHONPIP% install tables-3.1.1-cp27-none-win_amd64.whl
   %PYTHONPIP% install virtualenv-12.1.1-py2.py3-none-any.whl

   %PYTHONPIP% install pywin32-219-cp27-none-win_amd64.whl
   C:\Python27\Scripts\pywin32_postinstall.py -install


A straightforward set of steps is required to get the `ISAPI
WSGI <http://code.google.com/p/isapi-wsgi/>`_ handler for OMERO.web
working with your IIS deployment.

-  Ensure that the ISAPI for IIS options are installed.
-  Download and install `an ISAPI WSGI
   <http://code.google.com/p/isapi-wsgi/downloads/list>`_.
   If you download the *Source Distribution* (should be compatible with all
   versions of Windows/IIS) unzip the archive and run::

        python setup.py install

   Alternatively if you are using a 32-bit system you can use the *Windows
   Installer*.
-  For extended compatibility with multiple IIS versions ISAPI WSGI uses
   the IIS 6 WMI interface to interact with your IIS deployment. If
   you are using IIS 7 you must enable the IIS 6 WMI backwards
   compatibility options. Also make sure to install the ISAPI extensions
   and filters, as shown in the figure below. 
   For further information see `IIS Documentation - ISAPI Filters <https://www.iis.net/configreference/system.webserver/isapifilters>`_ 
   respectively `IIS Documentation - ISAPI/CGI Restrictions <https://www.iis.net/configreference/system.webserver/security/isapicgirestriction>`_

.. figure:: /images/installation-images/IIS8Requirements.png
   :align: center
   :width: 35%
   :alt: IIS 8 configuration options

   IIS 8 configuration options



-  The :guilabel:`Advanced Settings...` for the application pool
   assigned to your default site require modification using the *IIS Manager* as follows:

   - :guilabel:`Idle Time-out (minutes)` - to stop the worker process from
     suspending during inactivity periods, this setting needs to be
     changed to 0.

.. figure:: /images/installation-images/IIS8ApplicationPool.png
   :align: center
   :width: 35%
   :alt: IIS 8 Application Pool Advanced Settings

   IIS 8 Application Pool Advanced Settings


-  To avoid rendering errors on OMERO.web it is recommended to add the custom
   HTTP response header in the Web site pane.

.. figure:: /images/installation-images/IIS7HTTPresponseheader.png
   :align: center
   :alt: IIS 7 HTTP response header

-  Make sure that OMERO's log directory has full read/write permissions for all users

.. figure:: /images/installation-images/log_permissions.png
   :align: center
   :alt: Log folder permissions

-  Configure OMERO.web bindings for IIS

   ::

       C:\OMERO.server> bin\omero web iis

   This will automatically add two applications, `/omero` and `/static`,
   to the default web site and application pool. You can customize these
   locations by setting :property:`omero.web.prefix` and
   :property:`omero.web.static_url`.

   .. note::  You can make manual changes to the IIS OMERO configuration
       but they may be lost when OMERO.server is upgraded.

   .. note::  As OMERO.web 5 is based on `Django 1.8`_,
       :property:`omero.web.session_engine` and 
       :property:`omero.web.caches` should be unset.

       ::

           C:\omero_dist>bin\omero config set omero.web.session_engine
           C:\omero_dist>bin\omero config set omero.web.caches

       If your deployment requires additional cache store please follow the
       :djangodoc:`Django documentation <topics/cache/>`
       for more details.