Note

This documentation is for the new OMERO 5.3 version. See the latest OMERO 5.2.x version or the previous versions page to find documentation for the OMERO version you are using if you have not upgraded yet.

Setting up OMERO.web

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 the ability to manage users and groups.

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

• WSGI using a WSGI capable web server such as nginx and gunicorn
• the built-in Django lightweight development server (for testing only; see the OMERO.web deployment for developers page)

If you need help configuring your firewall rules, see Server security and firewalls for more details.

Deployment

Deploying OMERO.web separately from OMERO.server is recommended as they perform best under different circumstances and require a different set of dependencies. See OMERO.web WSGI deployment for more details.

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 Customizing your OMERO.web installation for additional customization options.

Depending upon which platform you are using, you may find a more specific walk-through listed below.

See also

OMERO.web walkthrough installation CentOS 7 and IcePy 3.6

Instructions for installing OMERO.web from scratch on CentOS 7 with Ice 3.6.

OMERO.web walkthrough installation Ubuntu 16.04 and IcePy 3.6

Instructions for installing OMERO.web from scratch on Ubuntu 16.04 with Ice 3.6.

OMERO.web walkthrough installation Mac OS X and IcePy 3.6

Instructions for installing OMERO.web from scratch on on Mac OS X with Homebrew. It is aimed at developers since typically MacOS X is not suited for serious deployment.

Note

Support for Apache deployment has been dropped in 5.3.0.

If your organization’s policies only allow Apache to be used as the external-facing web-server you should configure Apache to proxy connections to an Nginx instance running on your OMERO server i.e. use Apache as a reverse proxy. For more details see Apache mod_proxy documentation.

Logging in to OMERO.web

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

• http://your_host/omero OR, for development server: http://localhost:4080

OMERO.web login

OMERO.web maintenance

If an attempt is made to access OMERO.web whilst it is not running, the generated Nginx configuration file will automatically display a maintenance page.

• Session cookies omero.web.session_expire_at_browser_close:

  • A boolean that determines whether to expire the session when the user closes their browser. See Django Browser-length sessions vs. persistent sessions documentation 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 Django file-based session documentation 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 daily cron job, see Django clearing the session store documentation for more information.

  • OMERO.web offers alternative session backends to automatically delete stale data using the cache session store backend, see Django cached session documentation for more details. After installing all the cache prerequisites set the following:

    $ bin/omero config set omero.web.session_engine django.contrib.sessions.backends.cache
    

    • Redis 2.8+ requires django-redis 4.4+:

      $ pip install -r OMERO.py/share/web/requirements-redis.txt
      $ bin/omero config set omero.web.caches '{"default": {"BACKEND": "django_redis.cache.RedisCache", "LOCATION": "redis://redis:6379/0"}}'
      

    • DEPRECATED: Memcached:

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

Customizing your OMERO.web installation

OMERO.web offers a number of configuration options. The configuration changes will not be applied until gunicorn is restarted using bin/omero web restart.

By default OMERO.web expects to be run from the root URL of the web server. This can be changed by setting omero.web.prefix and 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 Deployment).

The front-end webserver e.g. Nginx can be setup to run on a different host from OMERO.web. You will need to set omero.web.application_server.host to ensure OMERO.web is accessible on an external IP.

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

$ bin/omero web -h

The most popular configuration options include:

• Debug mode, see omero.web.debug.
• Customizing OMERO clients e.g. to add your own logo to the login page (omero.web.login_logo) or use an index page as an alternative landing page for users (omero.web.index_template). See Customize OMERO clients for further information.
• Enabling a public user see Public data in the repository.

Setting up CORS

Cross Origin Resourse Sharing allows web applications hosted at other origins to access resources from your OMERO.web installation. This can be achieved using the django-cors-headers app with additional configuration of OMERO.web. See the django-cors-headers page for more details on the settings.

Install the app and add it to the list of installed apps:

$ pip install django-cors-headers
$ bin/omero config append omero.web.apps '"corsheaders"'

Add the cors-headers middleware. Configuration of OMERO.web middleware was added in OMERO 5.3.2 and uses an ‘index’ to specify the ordering of middleware classes. It is important to add the CorsMiddleware as the first class and CorsPostCsrfMiddleware as the last, for example:

$ bin/omero config append omero.web.middleware '{"index": 0.5, "class": "corsheaders.middleware.CorsMiddleware"}'
$ bin/omero config append omero.web.middleware '{"index": 10, "class": "corsheaders.middleware.CorsPostCsrfMiddleware"}'

Specify which origins are allowed access:

$ bin/omero config set omero.web.cors_origin_whitelist '["hostname.example.com"]'

Or allow access from all origins:

$ bin/omero config set omero.web.cors_origin_allow_all True