Page Contents


Feature List

Previous topic

OMERO.server and PostgreSQL

Next topic

DEPRECATED: OMERO.web Apache and mod_wsgi deployment (Unix/Linux)

This Page


This documentation is for OMERO 5.2. This version is now in maintenance mode and will only be updated in the event of critical bugs or security concerns. OMERO 5.3 is expected in the first quarter of 2017.

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 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 (you can also use Apache 2.2+ with mod_wsgi enabled but this is not recommended for new installations as support has been deprecated as of OMERO 5.2.6 and is likely to be dropped during the 5.3.x line)
  • 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 the Server security and firewalls page.


  • OMERO and its prerequisites (see OMERO.server installation).

  • Python 2.7

    • Pillow should be available for your distribution. We currently do not

      support version 3.0+.

    • Matplotlib should be available for your distribution

  • A WSGI capable web server

Deployment (Unix/Linux)

There are a number of good ways to easily deploy OMERO.web. If you have installed Nginx or Apache, 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.


Support for Apache deployment is deprecated as of OMERO 5.2.6 and is likely be dropped during the 5.3.x line.

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 login

OMERO.web Maintenance (Unix/Linux)

  • 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
      • Memcached:

        $ bin/omero config set omero.web.caches '{"default": { "BACKEND": "django.core.cache.backends.memcached.MemcachedCache", "LOCATION": "", "TIMEOUT": "86400" } }'
      • EXPERIMENTAL: Redis 2.4+ requires django-redis-cache 1.6.5+:

        $ pip install django-redis-cache>=1.6.5
        $ bin/omero config set omero.web.caches '{"default": {"BACKEND": "redis_cache.RedisCache", "LOCATION": ""}}'


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

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

$ 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 (Unix/Linux)).

The front-end webserver (Nginx, Apache) can be setup to run on a different host from OMERO.web. You will need to set 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


Depending on the deployment choice, OMERO.web will not activate configuration changes until either gunicorn is restarted using bin/omero web restart (nginx) or the Apache webserver has been reloaded.

The most popular configuration options include: