Page Contents


Feature List

Previous topic

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

Next topic

OMERO.server Windows Service

This Page


This documentation is for the new OMERO 5.2 version. See the latest OMERO 5.1.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 Nginx and Gunicorn deployment (Unix/Linux)

Nginx Gunicorn configuration (Unix/Linux)


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 (LTS) which requires Python 2.7. For more information see Python on the Version requirements page.

Install Django 1.8 and Gunicorn using package requirements file:

$ pip install -r share/web/requirements-py27-nginx.txt


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

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.

Install gunicorn:

$ pip install gunicorn

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
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-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $http_host;
        proxy_redirect 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.

Start the Gunicorn worker processes running one thread listening on

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

Additional settings can be configured from command line arguments:

--workers WORKERS

The number of worker processes for handling requests.

--worker-connections WORKER_CONNECTIONS

The maximum number of simultaneous clients.

--wsgi-args WSGI_ARGS

Additional arguments. For more details check Gunicorn Documentation.

The Gunicorn 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 WSGI workers (PID 59217) killed.