Setup & Maintenance

Comprehensive guide to installing, configuring, and updating bMINTY using Docker.

1. Initial Installation

The simplest way to run bMINTY is with Docker. No external dependencies (Python/Node) are required.

# Clone the repository
git clone https://github.com/GeorgakilasLab/bMINTY
cd bMinty

# Start services (First time build)
docker compose up --build

2. Changing Ports

By default, the Frontend runs on 3000 and the Backend on 8000. To change this, you can use a .env file.

# Create .env file
cp .env.example .env

# Edit .env to set your preferred ports
FRONTEND_PORT=3001
BACKEND_PORT=8001

# Re-launch with new configuration
docker compose up --build

3. Accessing the Web Interface

Once the Docker containers are running successfully, the bMINTY web interface can be accessed directly from your browser.

• Default URL: http://localhost:3000
• Backend API (default): http://localhost:8000

If you changed the ports using the .env file, make sure to use the corresponding values instead.

FRONTEND_PORT=3001
BACKEND_PORT=8001

4. Updating bMINTY

To update your instance with the latest features from GitHub:

# 1. Stop current containers
docker compose down

# 2. Pull latest code
git pull origin main

# 3. Rebuild containers to apply changes
docker compose up --build

Quick Start with Test Data

To verify that your bMINTY installation is working correctly, you can import the included test database. It contains a small, pre-populated dataset of B cells from study SRP073767 and is around 25 MB in size.

Step 1 — Start bMINTY

Make sure your bMINTY instance is up and running before importing. If it is not, start it with:

docker compose up

Then open http://localhost:3000 in your browser. You should see the Explore Dashboard.

bMINTY running with an empty database — ready for import

Step 2 — Open the Import Wizard

Scroll to the footer of the Explore page. You will find the Import Data button there. Click it to open the Import Wizard.

Footer of the Explore page — click "Import Data" to open the wizard

Step 3 — Select "Import Entire Database"

In the Import Wizard dialog, choose the Import Entire Database option. This will replace the current database with the one you provide.

Import Wizard — select "Import Entire Database"

Step 4 — Upload the Test Database File

Click Choose File and navigate to test-data/SRP073767_b_cells.sqlite3 inside your local bMINTY repository clone. Then click Import to start the upload.

Select the test database file and click Import

Step 5 — Verify the Import

After a successful import, the Explore Dashboard will refresh and show the study SRP073767 with its associated assays and B cell data. If the study appears, your installation is working correctly.

Explore Dashboard after importing the test database — study SRP073767 should be visible

Explore Functionality

http://localhost:3000

Expanding Data Levels

Clicking on a Study row reveals associated Assays. Clicking an Assay reveals detailed metrics including pipeline info and assembly versions.

1. Expanding a Study

2. Viewing Assay Details

Modifying Metadata

You can edit study or assay details directly from the interface using the modify actions.

Editing Study Metadata

Editing Assay Metadata

While editing an assay, you can assign it to a different study.

Filtering Panel

The sidebar filter panel allows you to drill down into massive datasets using metadata tags. The filters are auto-filled from the database.

The Global Filter Sidebar

Applying Selection. To undo a selection, you can click the x button, both on the filter panel and the main view.

Click Reset Filters to reset all filters to their default values

Detailed Filter Categories

1. Study Filters

• Study Name: A short, human-friendly unique identifier for the study.
• Study External ID: A unique study identifier used to map the study to external repositories (e.g. GEO accession).
• Repository: The external repository that originally hosts the study data (e.g. GEO, ArrayExpress).
• Description: A detailed description of the purpose and context of the study.
• Note: Any note related to the study.

2. Assay Filters

• Assay Name: A short, human-friendly unique identifier for the assay.
• Assay External ID: The external id of the assay.
• Assay Type: The type of assay that was performed.
• Tissue: The tissue origin of the sample used for the assay.
• Cell Type: The cell type isolated from the sample (if applicable).
• Treatment: A brief description of any treatment applied prior to sampling.
• Platform: The platform or technology used to perform the assay.
• Note: Any note related to the assay.
• Target: The molecular target of the assay (e.g. DNA, RNA), if applicable.
• Date: The date on which the assay was performed.
• Kit: The kit used to prepare the sample for the assay.
• Description: A detailed description of the purpose of the assay.
• Availability: Indicates whether the assay is visible in the user interface.

3. Cell Filters

Filter by Cell type and Cell label.

4. Assembly Filters

Filter by Assembly Name (GRCh38, mm10) or Version.

5. Interval Filters

Filter by genomic interval Types (e.g., Peaks, Genes) or Biotypes.

Data Import Wizard

The wizard guides you through ingesting complex genomic datasets safely. You can either import an entire database or individual tables.

To access the wizard, select a button at the footer of the explore page.

Import Menu Selection

Import Entire SQLite Database. Select the create a backup option to safely backup your existing work.

Checksum Verification

When importing an entire database, you can optionally enter a SHA-256 checksum to verify file integrity before committing the import.

Checksums match — file integrity verified. The IMPORT button becomes available.

Checksum mismatch — the file may be corrupted. You can still proceed with IMPORT ANYWAY.

Step-by-Step Wizard to import individual data.

Scroll horizontally to view all steps:

Step 1: Create or Select an existing Study

Step 2: Create or Select an existing Pipeline

Step 3: Create or Select an existing Assay

Step 4: Create or Select an existing Assembly

Step 5: Add Intervals

Step 6: Add Cells

Step 7: Upload Signals

Exporting Data

Export your curated data for downstream analysis or publication. You can export the full database or a filtered subset.

Export Configuration Dialog, without filters applied

Export Configuration Dialog with Filters Applied

Export complete — a SHA-256 checksum is displayed and can be copied or downloaded as a .sha256 file to verify the exported data later.

Study Table

This table acts as the root of the data hierarchy, representing a coherent biological study.

Pipeline Table

Stores metadata about the bioinformatic pipelines used to generate the data.

Assay Table

Represents individual experiments performed within a study.

Assembly Table

Stores reference genome assembly information.

Interval Table

Defines genomic regions (peaks, genes, regulatory elements) of interest.

Cell Table

Stores single-cell or spatial resolution data points.

Signal Table

The core experimental data linking assays, intervals, and cells.

RO-Crate Metadata

When exporting with ?ro_crate=true, bMINTY wraps the export in a ZIP file alongside a ro-crate-metadata.json file conforming to the RO-Crate 1.2 specification. The metadata captures full provenance, export statistics, applied filters, file descriptions, and live-extracted database schemas — making the export self-describing and suitable for publication or long-term archival.

Backend API

bMINTY exposes a full REST API. A Swagger UI is available at http://localhost:8000/api/schema/swagger-ui/ for interactive documentation.

Swagger Documentation Interface