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 `_ (with `mod\_fastcgi `_ 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 :doc:`/sysadmins/server-security` page. Prerequisites ------------- - OMERO and its prerequisites (see :doc:`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 Configuring OMERO from the command line --------------------------------------- Configuration options can be set using the :omerocmd:`config set` command: :: $ bin/omero config set When supplying a value with spaces or multiple elements, use **single quotes**. The quotes will not be saved as part of the value (see below). To remove a configuration option (to return to default values where mentioned), simply omit the value: :: $ bin/omero config set These options will be stored in a file: ``etc/grid/config.xml`` which you can read for reference. **DO NOT** edit this file directly. You can also review all your settings by using: :: $ bin/omero config get which should return values without quotation marks. A final useful option of :omerocmd:`config edit` is: :: $ bin/omero config edit which will allow for editing the configuration in a system-default text editor. Quick Start ----------- Using FastCGI (Unix/Linux) ~~~~~~~~~~~~~~~~~~~~~~~~~~ Once you have installed a FastCGI capable web server, configuration of OMERO.web is quite straightforward. - OMERO.web is configured to use FastCGI TCP by default. If you are using a non-standard web server configuration you may wish to change this before generating your web server configuration: :: $ bin/omero config set omero.web.application_server "fastcgi" / "fastcgi-tcp" The default `fastcgi-tcp` option uses a TCP connection for communication between OMERO.web and your web server; `fastcgi` uses a file based socket and will require you to manage the file permissions on it. - By default OMERO.web expects to be run from the root URL of the web server. It can be configured to run from a sub-directory, for example `http://example.org/omero/`, as follows: :: $ bin/omero config set omero.web.force_script_name '/omero' $ bin/omero config set omero.web.static_url '/omero/static/' - **Place one of the below stanza in your web server configuration file. The location of the file will depend on your system, please refer to your web server's manual. Apache and nginx configurations can be automatically generated for you by OMERO.web, see** :ref:`apache_configuration` **or** :ref:`nginx_configuration`. .. _apache_configuration: Apache configuration """""""""""""""""""" 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 :: ... ### ### Stanza for OMERO.web created 2012-07-12 16:44:16.112099 ### FastCGIExternalServer "/usr/local/dev/openmicroscopy/dist/var/omero.fcgi" -host 0.0.0.0:4080 -idle-timeout 60 Options -Indexes FollowSymLinks Order allow,deny Allow from all Options -Indexes FollowSymLinks Order allow,deny Allow from all Alias /omero/static /usr/local/dev/openmicroscopy/dist/lib/python/omeroweb/static Alias /omero "/usr/local/dev/openmicroscopy/dist/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 `_. .. _nginx_configuration: Nginx configuration """"""""""""""""""" To create a site configuration file for inclusion system-wide nginx instance configuration redirect the output of the following command into a file: :: $ bin/omero web config nginx --system :: server { listen 80; server_name $hostname; # weblitz django apps serve media from here location /omero/static { alias /usr/local/dev/openmicroscopy/dist/lib/python/omeroweb/static; } location /omero { if (-f /usr/local/dev/openmicroscopy/dist/var/maintenance.html) { error_page 503 /maintenance.html; return 503; } fastcgi_pass 0.0.0.0:4080; fastcgi_split_path_info ^(/omero)(.*)$; fastcgi_param PATH_INFO $fastcgi_path_info; fastcgi_param SCRIPT_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; } location /maintenance.html { root /usr/local/dev/openmicroscopy/dist/var; } } .. 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** .. figure:: /images/installation-images/login.png :align: center :width: 55% :alt: OMERO.webadmin login 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. .. _customizing_your_omero_web_installation_unix: Customizing your OMERO.web installation --------------------------------------- .. note:: For clarity, some edge-case/in-development options may not be documented below. For the full list see: :: $ bin/omero web -h OR look in lib/python/omeroweb/settings.py - A list of servers the Web client can connect to. Default: ``[["localhost", 4064, "omero"]]``. :: $ bin/omero config set omero.web.server_list '[["prod.example.com", 4064, "prod"], ["dev.example.com", 4064, "dev"]]' - Email server and notification: - (**REQUIRED**) From : address to be used when sending e-mail. Default: ``root@localhost`` :: $ bin/omero config set omero.web.server_email "webmaster@example.com" - (**REQUIRED**) Mail server hostname. Default: ``localhost``. :: $ bin/omero config set omero.web.email_host "email.example.com" - Mail server login username. Default: '' (Empty string). :: $ bin/omero config set omero.web.email_host_user "username" - Mail server login password. Default: '' (Empty string). :: $ bin/omero config set omero.web.email_host_password "password" - Mail server port. Default: ``25``. :: $ bin/omero config set omero.web.email_host_port "2255" - Use TLS when sending e-mail. Default: ``False``. :: $ bin/omero config set omero.web.email_use_tls "True" - Subject prefix for outgoing e-mail. Default: ``"[Django] "``. :: $ bin/omero config set omero.web.email_subject_prefix "Subject prefix for outgoing e-mail" - Controlling displayed scripts: - Since OMERO 4.3.2, OMERO.web has the ability to dynamically display scripts in the script runner menu just like OMERO.insight. Some scripts were not suitable for display initially and are excluded from the menu. You may wish to control which scripts your users can see in OMERO.web using this configuration option. Default: ``'["/omero/figure_scripts/Movie_Figure.py", "/omero/figure_scripts/Split_View_Figure.py", "/omero/figure_scripts/Thumbnail_Figure.py", "/omero/figure_scripts/ROI_Split_Figure.py", "/omero/export_scripts/Make_Movie.py"]'`` :: $ bin/omero config set omero.web.scripts_to_ignore '[]' $ bin/omero config set omero.web.scripts_to_ignore '["/omero/my_scripts/really_buggy.py", … ]' - Customizing index page: - Occasionally, a pre-login custom page may be required for OMERO.web. By creating a custom HTML page and setting ``INDEX_TEMPLATE``, it is possible to have an index page that, for example, will serve webstart and link to the webclient under your main domain. :: $ bin/omero config set omero.web.index_template 'webstart/start.html' - It is also possible to put the index HTML page in a custom location outside of OMERO.web by adding it to ``TEMPLATE_DIRS`` :: $ bin/omero config set omero.web.template_dirs '["/path/to/templates_dir"]' $ bin/omero config set omero.web.index_template 'start.html' .. _install_web_public_user: - Enabling a public user (automatically log in a public user, OMERO 4.4.0 onwards): - First, create a public user. You can use any username and password you wish. If you do not want this user to be able to modify any of the data they see, you should put this user in a Read-Only group and the public data should be owned by another member(s) of this group. - Enable the OMERO.web public user functionality, which is disabled (False) by default. :: $ bin/omero config set omero.web.public.enabled True - Set a URL filter for which the OMERO.web public user is allowed to navigate. Default: ``^/(?!webadmin)`` (`Python regular expression `_). You probably do not want the whole webclient UI to be publicly visible (although you could do this). The idea is that you can create the public pages yourself (see :doc:`/developers/Web`) since we do not provide public pages. E.g. to allow only URLs that start with '/my\_web\_public' you would use: :: $ bin/omero config set omero.web.public.url_filter '/my_web_public' Exotic matching techniques can be used but more explicit regular expressions are needed when attempting to filter based on a base URL: :: 'webtest' matches '/webtest' but also '/webclient/webtest' 'dataset' matches '/webtest/dataset' and also '/webclient/dataset' '/webtest' matches '/webtest…' but also '/webclient/webtest' '^/webtest' matches '/webtest…' but not '/webclient/webtest' If you need more examples of how to configure public url filters, see the :doc:`/developers/Web/PublicData` page. - Server to authenticate against. Default: ``1`` (the first server in ``omero.web.server_list``) :: $ bin/omero config set omero.web.public.server_id 1 - Username to use during authentication. Default: ``Not set.`` (required if ``omero.web.public.enabled=True``): :: $ bin/omero config set omero.web.public.user '__public__' - Password to use during authentication. Default: ``Not set.`` (required if ``omero.web.public.enabled=True``): :: $ bin/omero config set omero.web.public.password 'secret' - Administrator e-mail notification: - Admins list of people who get code error notifications. When debug mode is off and a view raises an exception, Django will e-mail these people with the full exception information. Default: ``[]`` (Empty list). :: $ bin/omero config set omero.web.admins '[["Dave", "dave@example.com"], ["Bob", "bob@example.com"]]' - Ping interval: - Since OMERO 4.4.0, OMERO.web now pings the server to keep your session alive when you are logged in and have an active browser window. The duration between these pings can be configured. Default: ``60000.`` (every 60 seconds) :: $ bin/omero config set omero.web.ping_interval 12000 - Debug mode: - A boolean that turns on/off debug mode. Default: ``False``. :: $ bin/omero config set omero.web.debug "True" - Cache: - If your deployment requires additional cache store please follow `Django cache documentation `_ for more details. - Session cookies: - A boolean that determines whether to expire the session when the user closes their browser. See :djangodoc:`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 :djangodoc:`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 :djangodoc:`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 :djangodoc:`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 .. _custom_web_location: - Custom OMERO.web location: - By default OMERO.web expects to be run from the root URL of the web server. It can be configured to run from a sub-directory, for example `http://example.org/omero/`, as follows: :: $ bin/omero config set omero.web.force_script_name '/omero' $ bin/omero config set omero.web.static_url '/omero/static/' - Update your web server configuration. For example, in the nginx configuration replace :: fastcgi_param PATH_INFO $fastcgi_script_name; with :: fastcgi_split_path_info ^(/omero)(.*)$; fastcgi_param PATH_INFO $fastcgi_path_info; fastcgi_param SCRIPT_INFO $fastcgi_script_name; - If `omero.web.force_script_name` is set then ``$ bin/omero web config nginx --system`` will automatically generate the correct configuration. - Configuring additional web apps: - The OMERO.web framework allows you to add additional Django apps. For an example with installation instructions, see `webmobile `_ - Download or clone from the git repository into the /omeroweb/ directory, then run :: $ bin/omero config set omero.web.apps '[""]' - Customizing webclient login page: - You can customize the webclient login page with your own logo. Logo images should ideally be 150 pixels high or less and will appear above the OMERO logo. - You will need to host the image somewhere else and link to it with :: $ bin/omero config set omero.web.login_logo "http://www.openmicroscopy.org/site/logo.jpg"