back Remote volumes

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

Typically the 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 or video (e.g. in the annotation tool), the application receives the request, loads the file from a storage disk and returns the 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 files. This means that you have to transfer all the files 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 or video in BIIGLE, your browser doesn't care where this file 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 file is served to redirect your request there. And this remote location can be under your control. In addition to that, a remote location may speed up loading times of the files if your internet connection to the BIIGLE server is rather slow but the connection to the remote location is fast. This can be particularly effective for large video files.

How to set up a remote location

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

Once the remote location is set up you can create a new volume with the files. Just enter the first part of the location (http(s)://<domain>/<subdirectories>) as the volume URL and a comma separated list of all filenames (<file>) as files. BIIGLE will automatically detect volume files 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 files 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 files 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 files from remote sources in BIIGLE. Although those files can be displayed, BIIGLE cannot access the raw data in the browser which is a requirement for some features of the image annotation tool. 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 files from remote sources just like regular files.

To set up CORS for the files of your remote source, you have to update the configuration of the webserver that serves the files. 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 "*"
Access-Control-Allow-Headers "x-csrf-token, x-requested-with"

In addition to that, you have to use a secure HTTP connection (https://) to access the files. BIIGLE detects if CORS is properly configured for remote files 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 image annotation tool.
  • The magic wand interaction in the image annotation tool.
  • The screenshot button in the image 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).

A method to prevent unauthorized access to the files 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 files, 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 directory and/or the files. If your remote location URL is https://your-institute.com/files, 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:


In addition to a URL that is hard to guess, you should make sure to use secure HTTP connections. This means that you should always use https:// URLs instead of http:// URLs.