OMERO.openlink

An OMERO.web plugin that creates openly accessible links (URLS for raw files) to your data in OMERO and a batch file to download the data with 'curl'.

Main application:

• Bundle data of different groups/projects/datasets
• Fast web download
• Data sharing via link

Requirements

• OMERO.web 5.6.0 or newer
• nginx server configurations

Installation

This section assumes that an OMERO.web is already installed and you will use the nginx server to provide the URL's.

Prerequisite

Variable OPENLINK_DIR: You have to define a directory on your OMERO.server (here /path/to/open_link_dir), where your nginx server has access. The system user omero-server requires read and write access to this directory for link generation. If you want to use the plugin, omero-web also needs read and write access. Please specify the full path to this directory under OPENLINK_DIR.

Install the app using pip <https://pip.pypa.io/en/stable/>_

NB: You need to ensure that you are running pip from the python environment where omero-web is installed. Depending on your install, you may need to call pip with, for example: /path/to_web_venv/venv/bin/pip install ...

::

$pip install -U omero-openlink

Add OpenLink app to your installed web apps:

::

$omero config append omero.web.apps '"omero_openlink"'

Display the OpenLink pane in the right pane

::

$omero config append omero.web.ui.right_plugins '["OpenLink", "omero_openlink/webclient_plugins/right_plugin.openlink.js.html", "openlink_tab"]'

Additional configuration settings:

::

# path of prepared OPENLINK_DIR, here as eaxmple */storage/openlink*
$omero config set omero.web.openlink.dir '/storage/openlink'
# set the url alias of your OMERO.web server without leading http://. Here as example we use the address of the openmicroscopy demo server
$omero config set omero.web.openlink.servername 'demo.openmicroscopy.org'
# http or https
$omero config set omero.web.openlink.type_http 'https'
# nginx location for openlink data, here as example /openlink; would result in the url https://demo.openmicroscopy.org/openlink
$omero config set omero.web.openlink.nginx_location '/openlink'

Reload your system and restart the OMERO.web server:

Nginx configuration

This section assumes that an you use an nginx server.

Prerequisites: For the configuration you have to reuse the specified values for SERVER_NAME and OPENLINK_DIR. Specify the URL under which the data should be accessible:

::

SERVERNAME/SUBGROUP # this could be data.myorg.de/openlink

You can configure your nginx in two way's:

Option 1: Add a new location to your nginx configuration file (etc/nginx/conf.d/omeroweb.conf) like:

::

location  /SUBGROUP {
        proxy_read_timeout 36000;  # 10 hours
        limit_rate 10000M;  # 10 GByte
        gzip on;
        gzip_min_length 10240;
        disable_symlinks off;  # enable symlinks
        autoindex on;
        autoindex_format html; # html, xml, json, or jsonp
        autoindex_exact_size off; # on off
        autoindex_localtime on; # on off  (UTC)
        alias OPENLINK_DIR;  # the links will be created here
}

Option 2: Or create a new website for nginx by create a new file (e.g. openlink.conf) in /etc/nginx/conf.d/ with:

::

server {
    listen 80;
    server_name SERVER_NAME;  # url alias to this nginx site

    location /SUBGROUP {

        proxy_read_timeout 36000;  # 10 hours
        limit_rate 10000M;  # 10 GByte
        gzip on;
        gzip_min_length 10240;
        disable_symlinks off;  # enable symlinks
        autoindex on;
        autoindex_format html; # html, xml, json, or jsonp
        autoindex_exact_size off; # on off
        autoindex_localtime on; # on off  (UTC)
        alias OPENLINK_DIR;  # the links will be created here
    }
}

Note: To use a special style (like the example in scripts/nginx/autoIndexStyle.xslt) for your openlink data representation, please copy the style file to /etc/nginx and use the following configuration:

::

autoindex_format  xml;
xslt_stylesheet /etc/nginx/autoindexStyle.xslt       path="$uri" schema="$scheme" host="$host";

If a user navigates to a URL that corresponds to a directory on the server, NGINX looks for an index file to serve. By default, this is usually index.html. If this file is present, NGINX will serve its contents instead of displaying a directory listing. It is recommendet to put such a index.html in the OPENLINK_DIR to avoid the listing of all created openlink data.

Example for index.html

::

<!DOCTYPE html>
<html lang="de">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Omero Downloads</title>
  </head>
  <body>
  <a href="https://data.myorg.de/openlink">Please go first to the Omero-System to create DownloadLinks!</a>
  </body>
</html>

Enable openlink creation

This section assumes that an OMERO.server is already installed.

Openlink can be created using a script that runs on the OMERO.server. This script needs to be uploaded to the OMERO.server and its dependencies installed in the OMERO.server virtual environment.

The script can be uploaded using two alternative workflows, both of which require you to have the correct admin privileges. To find where OMERO.openlink has been installed using pip, run:

::

$pip show omero-openlink

The command will display the absolute path to the directory where the application is installed e.g. ~/<virtualenv_name>/lib/python3.6/site-packages. Go to that directory.

Before uploading please edit the configuration section of omero_openlink/scripts/omero/util_scripts/Create_OpenLink.py.

Note OPENLINK_DIR, SERVER_NAME,TYPE_HTTP, NGINX_LOCATION should have the same values like specified in the config of OMERO.web. Because the script is running on the OMERO.server, there is no way to transfer the config parameters automatically.

::

# Directory for links that the nginx server also has access to as specifed in OMERO web config
OPENLINK_DIR = "/path/to/open_link_dir"

# name of nginx website as specifed in OMERO web config
SERVER_NAME = "omero-data.myfacility.com"

# type of hypertext transfer protocol (http or https) as specifed in OMERO web config
TYPE_HTTP = "https"

# email originator
ADMIN_EMAIL = "myemail@yourfacilitydomain"

# filename with links to single files
LINKS_FILE = "links_to_data.txt"

# length of hash string used in the openlink url
LENGTH_HASH = 12

# email server IP adress
SMTP_IP = "127.0.0.1"

# nginx location for openlink data as specifed in OMERO web config
NGINX_LOCATION = ""  # '/openlink'

Option 1: Connect to the OMERO server and upload the script via the CLI. It is important to be in the correct directory when uploading so that the script is uploaded with the full path: omero/utils_scripts/Create_OpenLink.py:

::

$cd omero_openlink/scripts
$omero script upload omero/util_scripts/Create_OpenLink.py --official

Option 2: Alternatively, before starting the OMERO.server, copy the script from the figure install /omero_openlink/scripts/omero/util_scripts/Create_OpenLink.py to the OMERO.server path/to/OMERO.server/lib/scripts/omero/util_scripts. Then restart the OMERO.server.

Option 3: Upload the script through the OMERO web interface: For this, log into your OMERO web interface as admin, select the scripts icon and click on the "Upload Script" button. Select the Create_OpenLink.py script from the directory where you copied it to locally and upload it into the directory omero/util_scripts.

Validation

Validation of configuration in Create_OpenLink.py

In order to check whether the values for x have been entered correctly, please test the link that was entered in the log file under URL and also check the entered url's in the batch_download.curl that is available there.

Validation of configuration omero-openlink

There is a debug output available for the plugin. Go to subdirectory omero_openlink of the installation directory of omero-openlink

::

$ cd omero-openlink/omero_openlink

open the urls.py and delete the leading # in the line

::

#url(r'^debugoutput/$',views.debugoutput,name='debugoutput'),

After restarting the web server, find the debug output for your Openlink plugin by replacing webclient by oemro_openlink/debugoutput in the URL of the omero.web (for example: https://server.openmicroscopy.org/webclient -> https://server.openmicroscopy.org/omero_openlink/debugoutput). This output shows you:

• what is defined under OPENLINK_DIR, SERVER_NAME
• check if OPENLINK_DIR is accessible
• check permission of OPENLINK_DIR for omero-web user
• overview of OpenLink Areas of currently logged-in user

License

OMERO.openlink is released under the AGPL.