Page Contents


Feature List

Previous topic

Setting up OMERO.web

Next topic

OMERO.web walkthrough installation CentOS 7 and IcePy 3.6

This Page


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.

OMERO.web WSGI 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.

This guide uses the example of deploying OMERO.web separately from OMERO.server with Nginx and gunicorn.


  • Python 2.7
    • virtualenv (optional) tool to create isolated Python environments
    • PyPI a package management system used to install and manage software packages written in Python. PyPI is already installed if you are using Python 2 >=2.7.9
    • omego OME package management system
    • ZeroC IcePy 3.6
    • Pillow <3.4
    • NumPy >=1.9
  • A WSGI-capable web server such as nginx and gunicorn,

Default configuration

If you wish to install the dependencies in a virtual environment, you will first have to create one and activate it. The following step is optional:

$ virtualenv omeroweb
$ source omeroweb/bin/activate

Install the OMERO.web dependencies using the package management tools:

$ pip install omego
$ omego download --ice "3.6" py
$ zip=$(ls*.zip)
$ zipname=${}
$ rm -f $zip
$ mv $(find . -name '*' -type d) `pwd`/
$ pip install -r


For more details refer to how to install Django 1.8 or upgrade Django to 1.8.

Additional Gunicorn configuration

Additional settings can be configured by changing the following properties:

Nginx configuration

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.

Set the following:

$ bin/omero config set omero.web.application_server "wsgi-tcp"

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

$ web config nginx
upstream omeroweb {
    server fail_timeout=0;

server {
    listen 80;
    server_name $hostname;

    sendfile on;
    client_max_body_size 0;

    # maintenance page serve from here
    location @maintenance {
        root /home/omero/OMERO.server/etc/templates/error;
        try_files $uri /maintainance.html =502;

    # weblitz django apps serve media from here
    location /static {
        alias /home/omero/OMERO.server/lib/python/omeroweb/static;

    location @proxy_to_app {
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $http_host;
        proxy_redirect off;
        proxy_buffering off;

        proxy_pass http://omeroweb;

    location / {

        error_page 502 @maintenance;
        # checks for static file, if not found proxy to app
        try_files $uri @proxy_to_app;


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.


If you need help configuring your firewall rules, see the Server security and firewalls page.

Running OMERO.web

Start the Gunicorn worker processes listening by default on

$ web start
... static files copied to '/home/omero/OMERO.server/lib/python/omeroweb/static'.
Starting OMERO.web... [OK]

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

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

Download limitations

In order to offer users the ability to download data from OMERO.web you have to deploy using EXPERIMENTAL: Async workers. OMERO.web is able to handle multiple clients on a single worker thread switching context as necessary while streaming binary data from OMERO.server. Depending on the traffic and scale of the repository you should configure connections and speed limits on your server to avoid blocking resources. We recommend you run benchmark and performance tests. It is also possible to apply Download restrictions and offer alternative access to binary data.


Handling streaming request/responses requires proxy buffering to be turned off. For more details refer to Gunicorn deployment and Nginx configuration.


We run example benchmarks on rendering thumbnails and 512x512 pixels planes for 100 concurrent users making 5000 requests in total:

$ ab -n 5000 -c 100
This is ApacheBench, Version 2.3 <$Revision: 1706008 $>
Copyright 1996 Adam Twiss, Zeus Technology Ltd,
Licensed to The Apache Software Foundation,

Benchmarking (be patient)
Completed 100 requests
Completed 200 requests
Completed 300 requests
Completed 400 requests
Completed 500 requests
Finished 500 requests

Server Software:        nginx/1.11.10
Server Hostname:
Server Port:            80

Document Path:          /omero/webclient/render_thumbnail/1234/
Document Length:        4405 bytes

Concurrency Level:      20
Time taken for tests:   17.904 seconds
Complete requests:      500
Failed requests:        0
Total transferred:      2271500 bytes
HTML transferred:       2202500 bytes
Requests per second:    27.93 [#/sec] (mean)
Time per request:       716.144 [ms] (mean)
Time per request:       35.807 [ms] (mean, across all concurrent requests)
Transfer rate:          123.90 [Kbytes/sec] received

Connection Times (ms)
              min  mean[+/-sd] median   max
Connect:       45   49   4.3     48      83
Processing:   245  650 113.4    620    1167
Waiting:      244  649 113.4    620    1167
Total:        294  699 113.0    670    1214

Percentage of the requests served within a certain time (ms)
  50%    670
  66%    698
  75%    737
  80%    754
  90%    814
  95%    951
  98%   1070
  99%   1080
 100%   1214 (longest request)


In order to identify why OMERO.web is not available run:

$ web status

Then consult nginx error.log and OMERO.server/var/log/OMEROweb.log

Check OMERO.web issues for more details.


To run the WSGI server in debug mode, enable Gunicorn logging using omero.web.wsgi_args:

$ config set omero.web.wsgi_args -- "--log-level=DEBUG --error-logfile=/home/omero/OMERO.server/var/log/error.log".

EXPERIMENTAL: Gunicorn advanced configuration


The following configuration options marked as EXPERIMENTAL have yet to be extensively tested in a production environment, use at your own risk.

OMERO.web deployment can be configured with sync and async workers. Sync workers are faster and recommended for a data repository with Download restrictions. If you wish to offer users the ability to download data then you have to use async workers; read more about Download limitations above.

See Gunicorn design for more details.

EXPERIMENTAL: Sync workers

  • Install futures

    $ pip install futures

Additional settings can be configured by changing the following properties:

  • The number of worker threads for handling requests, see Gunicorn threads

    $ config set omero.web.wsgi_worker_class
    $ config set omero.web.wsgi_threads $(2-4 x NUM_CORES)

EXPERIMENTAL: Async workers

Additional settings can be configured by changing the following properties:

  • The maximum number of simultaneous clients, see Gunicorn worker-connections

    $ config set omero.web.wsgi_worker_class gevent
    $ config set omero.web.wsgi_worker_connections 1000
    $ config set omero.web.application_server.max_requests 0