Hosting a local instance

To use the Viewer with locally generated BlobDir datasets, you will need to host a local instance of the Viewer. Convenience methods exist within BlobTools2 (see BlobTools 2 tutorial Opening a dataset in the Viewer) to start the Viewer with no additional configuration but more options are available when starting the Viewer directly. This page contains instructions for hosting a private locally hosted instance and is not intended to be used as guidance for hosting a publicly accessible instance.

The Viewer comprises two components, an Application Programming Interface (API) that loads a directory of BlobDir datasets and makes them available to the Viewer client, which is the portion that loads in the browser for interactive visualisation. Configuration options for both of these components can be set using the command line options. The only option that is essential is the path to a directory containing BlobDir datasets.

Example

conda activate btk
blobtools host /path/to/dir/containing/blobdirs

You should see a message like the following:

Starting BlobToolKit API on port 8000 (pid: 11103)
Starting BlobToolKit viewer on port 8080 (pid: 11105)
Visit http://localhost:8080 to use the interactive BlobToolKit Viewer.

Go to http://localhost:8080/view/all in a web browser to start exploring your datasets.

If the Viewer is running on a remote server to which you have ssh access, datasets can be viewed interactively by forwarding ports 8000 (default API port) and 8080 (default client port) using a command similar to ssh -L 8000:127.0.0.1:8000 -L 8080:127.0.0.1:8080 username@remote_host before visiting the Viewer URL as above.

If you see a message that the api port or viewer port is already in use, you can change the ports using the --api-port and --port options. You can also change the default hostname (localhost) if you need to:

blobtools host \
  --api-port 8001 \
  --port 8002 \
  --hostname test.genomehubs.org \
  /path/to/dir/containing/blobdirs