BlobToolKit Viewer and API Setup#

The BlobToolKit viewer is a browser-based genome assembly visualization tool. It is served by two cooperating processes: blobtoolkit-api (a Node.js/Express server) and blobtoolkit-viewer (a static web client). Both are distributed as standalone binaries for Linux and macOS 1 and can also be installed via pip install "blobtoolkit[full]" 2.

Architecture#

Browser
  └── blobtoolkit-viewer (default: port 8080)
        └── blobtoolkit-api (default: port 8000)
              └── BTK_FILE_PATH/ ← BlobDir datasets on disk

The viewer serves the frontend; all dataset reads go through the API. The API entry point is src/api/src/app.js, which reads src/api/src/config/main.js and starts an HTTP (or HTTPS) Express server on BTK_API_PORT.

Quick Start#

Download the binaries and start both processes 3:

RELEASE=4.1.5
PLATFORM=linux # or macos
curl -L https://github.com/blobtoolkit/blobtoolkit/releases/download/${RELEASE}/blobtoolkit-api-${PLATFORM} > blobtoolkit-api
curl -L https://github.com/blobtoolkit/blobtoolkit/releases/download/${RELEASE}/blobtoolkit-viewer-${PLATFORM} > blobtoolkit-viewer
chmod 755 blobtoolkit-*

BTK_API_PORT=8880 BTK_PORT=8881 BTK_FILE_PATH=/path/to/datasets ./blobtoolkit-api
BTK_API_PORT=8880 BTK_PORT=8881 ./blobtoolkit-viewer

Open http://localhost:8881/view/all in a browser. If ports are omitted, the defaults are BTK_API_PORT=8000 and BTK_PORT=8001 4.

Environment Variables#

All configuration is driven by environment variables (or a .env file placed alongside the binary). The canonical defaults are in src/api/.env.dist and resolved in src/api/src/config/main.js.

The viewer and API must agree on BTK_API_PORT and BTK_PORT; the viewer uses these values to construct the API URL it queries 15.

Dataset Resolution (BTK_FILE_PATH)#

On startup, the API walks BTK_FILE_PATH recursively, treating any subdirectory that contains a meta.json (or meta.json.gz) as a BlobDir dataset. Each dataset is indexed by assembly name, accession, taxon, and revision. The resolved config.filePath is also stored in each dataset's meta object for subsequent field reads 16.

• Datasets are discovered in a two-pass strategy: a fast listMeta pass runs immediately on startup, followed by a slower readMeta pass (with full metadata parsing) that loads 10 seconds later 17.
• A live reload of the index can be triggered via GET /api/v1/search/reload/<BTK_RELOAD_KEY> without restarting the server 18.

Remote Access via SSH Tunneling#

When the API and viewer run on a remote server, forward both ports to your local machine 19:

ssh -L 8880:localhost:8880 -L 8881:localhost:8881 user@remote-server

Then open http://localhost:8881/view/all locally. No additional configuration is needed because the viewer is already configured to call localhost:<BTK_API_PORT>.

CORS note: If the viewer and API are on different hosts or ports in other setups, add the viewer's origin to BTK_ORIGINS (space-separated) so the API accepts the requests 20.

HTTPS#

Set BTK_HTTPS=true and provide paths to your key and certificate 21:

BTK_HTTPS=true BTK_KEYFILE=/path/to/key.pem BTK_CERTFILE=/path/to/cert.pem ./blobtoolkit-api

The API then creates an HTTPS server and the constructed BTK_API_URL uses the https:// scheme automatically 22.

Key Source Files#