Note

This documentation is for the new OMERO 5.1. version. See the latest OMERO 5.0.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 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 OMERO.webadmin for managing users and groups.

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

FastCGI using a FastCGI capable web server such as Apache 2.2 (with mod_fastcgi enabled), Apache 2.4+ (with the bundled mod_proxy_fcgi enabled), nginx or lighttpd (since OMERO 4.2.1)
The built-in Django lightweight development server (for testing only)

You can find more information about FastCGI and where to get modules or packages for your distribution on the FastCGI website.

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

Prerequisites¶

OMERO and its prerequisites (see OMERO.server installation).
Python 2 (2.6 or later)
- Pillow should be available for your distribution
- Matplotlib should be available for your distribution
A FastCGI capable web server

Quick Start¶

FastCGI Configuration (Unix/Linux)¶

If you have installed Nginx or Apache OMERO can automatically generate a configuration file for your web server, see Apache 2.2 configuration (mod_fastcgi), Apache 2.4+ configuration (mod_proxy_fcgi) or Nginx configuration. 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.

Apache 2.2 configuration (mod_fastcgi)¶

Install mod_fastcgi. To create a site configuration file for inclusion in the main Apache configuration redirect the output of the following command into a file:

$ bin/omero web config apache

###

FastCGIExternalServer "/home/omero/OMERO.server/var/omero.fcgi" -host 127.0.0.1:4080 -idle-timeout 60

<Directory "/home/omero/OMERO.server/var">
    Options -Indexes FollowSymLinks
    Order allow,deny
    Allow from all
</Directory>

<Directory "/home/omero/OMERO.server/lib/python/omeroweb/static">
    Options -Indexes FollowSymLinks
    Order allow,deny
    Allow from all
</Directory>

<Directory "/home/omero/OMERO.server/etc/templates/error">
    Options -Indexes FollowSymLinks
    Order allow,deny
    Allow from all
</Directory>

<Location />
    ErrorDocument 500 /error/maintainance.html
</Location>

Alias /error /home/omero/OMERO.server/etc/templates/error
Alias /static /home/omero/OMERO.server/lib/python/omeroweb/static
Alias / "/home/omero/OMERO.server/var/omero.fcgi/"

Note

The default configuration file installed with mod_fastcgi may be incompatible with OMERO. In particular, the FastCGIWrapper option conflicts with FastCGIExternalServer required by OMERO and must be removed or commented out.

Note

To configure an HTTPS server follow the Apache documentation.

Apache 2.4+ configuration (mod_proxy_fcgi)¶

The mod_proxy_fcgi, mod_proxy and mod_rewrite Apache modules should already be installed and enabled as part of the Apache installation, if this is not the case then enable them. To create a site configuration file for inclusion in the main Apache configuration redirect the output of the following command into a file:

$ bin/omero web config apache-fcgi

###
### Stanza for OMERO.web created 2015-03-31 16:22:30.166216
###

RewriteEngine on

<Directory "/home/omero/OMERO.server/var">
    Options -Indexes +FollowSymLinks
    Require all granted
</Directory>

<Directory "/home/omero/OMERO.server/lib/python/omeroweb/static">
    Options -Indexes +FollowSymLinks
    Require all granted
</Directory>

<Directory "/home/omero/OMERO.server/etc/templates/error">
    Options -Indexes +FollowSymLinks
    Require all granted
</Directory>

<Location fcgi://127.0.0.1:4080/>
    Require all granted
</Location>

<Location /.fcgi/>
    ErrorDocument 503 /error/maintainance.html
</Location>

Alias /error /home/omero/OMERO.server/etc/templates/error
Alias /static /home/omero/OMERO.server/lib/python/omeroweb/static

RewriteCond %{REQUEST_URI} !^(/static|/.fcgi|/error)
RewriteRule ^(/|$)(.*) /.fcgi/$2 [PT]
SetEnvIf Request_URI . proxy-fcgi-pathinfo=1
ProxyPass /.fcgi/ fcgi://127.0.0.1:4080/

Nginx configuration¶

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

    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 / {

            error_page 502 @maintenance;

            fastcgi_pass 127.0.0.1:4080;

            fastcgi_param PATH_INFO $fastcgi_script_name;


            fastcgi_param REQUEST_METHOD $request_method;
            fastcgi_param QUERY_STRING $query_string;
            fastcgi_param CONTENT_TYPE $content_type;
            fastcgi_param CONTENT_LENGTH $content_length;
            fastcgi_param SERVER_NAME $server_name;
            fastcgi_param SERVER_PROTOCOL $server_protocol;
            fastcgi_param SERVER_PORT $server_port;
            fastcgi_pass_header Authorization;
            fastcgi_intercept_errors on;
            fastcgi_read_timeout 60;
            # Uncomment if nginx SSL module is enabled or you are using nginx 1.1.11 or later
            # -- See: #10273, http://nginx.org/en/CHANGES
            # fastcgi_param HTTPS $https;
        }

    }

Note

To configure an HTTPS server follow the nginx documentation. Make sure fastcgi_param HTTPS $https; is uncommented.

Note

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;
    ...
}

Starting OMERO.web¶

Start the Django FastCGI workers:

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

Note

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

Logging in to OMERO.web¶

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

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

OMERO.webadmin login

Note

This starts the server in the foreground. It is your responsibility to place it in the background, if required, and manage its shutdown.

OMERO.web Maintenance¶

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.
  Note
  
  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.caches '{"default": { "BACKEND": "django.core.cache.backends.memcached.MemcachedCache", "LOCATION": "127.0.0.1:11211", "TIMEOUT": "86400" } }' $ bin/omero config set omero.web.session_engine django.contrib.sessions.backends.cache

Note

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 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 FastCGI Configuration (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 omero.web.application_server.host to ensure OMERO.web is accessible on an external IP.

OMERO.web is configured to use FastCGI TCP by default. If you are using a non-standard web server configuration and wish to use a file based socket you can set omero.web.application_server to fastcgi. This is a highly specialized setup aimed at advanced users, so you will need to create your own web server configuration file, and file socket with correct permissions.

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.
Customize login page with your own logo, see omero.web.login_logo.
Customizing index page, see omero.web.index_template.
Enabling a public user see Public data in OMERO.web.

Page Contents

OMERO

Previous topic

Next topic

This Page

OMERO.web deployment¶

Prerequisites¶

Quick Start¶

FastCGI Configuration (Unix/Linux)¶

Apache 2.2 configuration (mod_fastcgi)¶

Apache 2.4+ configuration (mod_proxy_fcgi)¶

Nginx configuration¶

Starting OMERO.web¶

Logging in to OMERO.web¶

OMERO.web Maintenance¶

Customizing your OMERO.web installation¶

Navigation

Page Contents

OMERO

Previous topic

Next topic

Quick search

This Page

OMERO.web deployment¶

Prerequisites¶

Quick Start¶

FastCGI Configuration (Unix/Linux)¶

Apache 2.2 configuration (mod_fastcgi)¶

Apache 2.4+ configuration (mod_proxy_fcgi)¶

Nginx configuration¶

Starting OMERO.web¶

Logging in to OMERO.web¶

OMERO.web Maintenance¶

Customizing your OMERO.web installation¶

Navigation