×

back Remote volumes

With remote volumes you can use images from your own data source in BIIGLE.

Typically the image files of volumes are loaded through a network filesystem or even stored on the same machine that runs the BIIGLE application. If you request an image (e.g. in the annotation tool), the application receives the request, loads the image from a storage disk and returns the image file in the response.

Depending on where you come from (literally), this setup might pose some problems. Usually you want to work with your own images. This means that you have to transfer all the images to the people that run the BIIGLE instance. So first, you have to inconveniently transfer a large amount of data and second, you lose control of that data. This might not be a problem most of the time but sometimes you might want to keep (control of) your data.

This is where remote volumes come in. When you request an image in BIIGLE, your browser doesn't care where this image comes from. So it actually doesn't have to be served from the same machine that runs the BIIGLE application. Instead, BIIGLE only has to know the "remote" location from where the image is served to redirect your request there. And this remote location can be under your control. In addition to that, a remote image location may speed up loading times of the images if your internet connection to the BIIGLE server is rather slow but the connection to the remote location is fast.

How to set up a remote location for images

Images from a remote location must be accessible both by the BIIGLE application and your browser. The simplest setup is to make the images publicly available through a web server. After a successful setup you should be able to access the images in your browser via a URL like this https://your-institute.com/subdirectory/image_001.jpg. The domain, directory and image file names are just examples and can be completely arbitrary (http(s)://<domain>/<subdirectories>/<image file>).

Once the remote location is set up you can create a new volume with the images. Just enter the first part of the location (http(s)://<domain>/<subdirectories>) as the volume URL and a comma separated list of all image filenames (<image file>) as images. BIIGLE will automatically detect volume images coming from a remote location. The remote location should be available as long as the remote volume exists in BIIGLE.

If you want to revoke access to the images of your remote location, just turn your webserver off. Although BIIGLE will keep all information of the volume (annotations, etc.) BIIGLE users won't be able to access the original images any more.

Cross-Origin Resource Sharing

The cross-origin policy is a security mechanism of web browsers that prevents malicious third parties from extracting sensitive information from your web pages. This includes cases like loading images from remote sources in BIIGLE. Although those images can be displayed, BIIGLE cannot access the raw image data in the browser which is a requirement for some features. Cross-Origin Resource Sharing (CORS) is a mechanism to manually configure exceptions for the cross-origin policy. With a correct CORS configuration, BIIGLE can process images from remote sources just like regular images.

To set up CORS for the images of your remote source, you have to update the configuration of the webserver that serves the images. Some cloud storage services specifically provide configuration options for CORS. The webserver has to add the following HTTP headers to any GET or OPTIONS HTTP request for an image:

Access-Control-Allow-Origin "https://biigle.de, https://www.biigle.de"
Access-Control-Allow-Headers "x-csrf-token, x-requested-with"

That's all. BIIGLE detects if CORS is properly configured for remote images and automatically enables or disables the respective features. The features that are disabled for remote images without CORS are:

  • Live color adjustment of images in the annotation tool.
  • The magic wand interaction in the annotation tool.
  • The screenshot button in the annotation tool. Use the usual functions of your operating system or browser to create screenshots manually.

How to secure a remote location

Note that every BIIGLE user who has access to the remote volume will always know and have access to your remote location as well (as long as it exists).

The simplest method to prevent unauthorized access to the images of your remote location is to keep the URL secret. This way only authorized BIIGLE users know and have access to the location. Although theoretically anyone has access to the images, the probability of someone accidentally stumbling on the correct URL can be kept as low as someone accidentally (or by brute force) guessing a correct password.

One way to keep this probability low is to use long random names for the image directory and/or the image files. If your remote location URL is https://your-institute.com/images, the directory name is an easy guess. But with https://your-institute.com/4e29be7a-4bfa-4a5e-98c4-c99ce6a94226 it becomes almost impossible to guess the URL.

Here is your personal random string that you can use as a directory name (a UUID 4). Refresh the page to get a new one:

2fd27a84-4c57-4125-823c-e08d511004f3

Another way is HTTP basic access authentication. With basic auth you can specify a username and password that has to be supplied in order to access the remote location. Let's say you have set up basic auth with the username "admin" and the password "eiYie8ou". To create a remote volume that uses these basic auth credentials, just format the volume URL like this: https://admin:eiYie8ou@your-institute.com. That is https://<username>:<password>@<domain>.

Never use basic auth without HTTP encryption. If you cannot access your remote location via an https URL, then you should not use basic auth.

It is also important to note, that HTTP basic auth credentials are always stored and sent in clear text. This basically means that basic auth is not more secure than the method with a long random directory name described previously! Every BIIGLE user who has access to the remote volume will see the basic auth credentials.