JBrowse web quick start

This guide sets up a self-hosted JBrowse Web instance with the @jbrowse/cli command-line tool: download JBrowse, add an assembly and tracks, and serve the result as a folder of files on a web server. The same folder opens in JBrowse Desktop with no server (JBrowse CLI with Desktop), and Embedded components puts a view in your own web app.

TLDR#

Adding an assembly or a track writes an entry to config.json and copies the data file next to it, so the folder is a self-contained static site: no database, no server-side code. The commands need Node.js 18+, samtools and tabix, and use placeholder filenames you swap for your own.

npm install -g @jbrowse/cli
jbrowse create jbrowse2 && cd jbrowse2

samtools faidx genome.fa
jbrowse add-assembly genome.fa --load copy

samtools index file.bam
jbrowse add-track file.bam --load copy

bgzip file.vcf
tabix file.vcf.gz
jbrowse add-track file.vcf.gz --load copy

jbrowse text-index
npx serve -S .

Reproduce it end to end#

build_quickstart_web.sh runs the same flow against the volvox sample data JBrowse ships, with a FASTA, a BAM, a BigWig, a VCF and a GFF3, every input pinned:

curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/build_quickstart_web.sh
bash build_quickstart_web.sh               # builds ./quickstart_web_build/jbrowse2
npx serve -S quickstart_web_build/jbrowse2 # then open the printed URL

Prerequisites#

• Node.js 18+, from NodeSource or NVM rather than apt, which installs old versions
• samtools: sudo apt install samtools or brew install samtools
• tabix: sudo apt install tabix or brew install htslib
• bcftools, optional, for sorting a VCF

Install and run#

npm install -g @jbrowse/cli   # or npx @jbrowse/cli in place of jbrowse below
jbrowse create jbrowse2       # downloads and unzips jbrowse-web
cd jbrowse2
npx serve -S .                # http://localhost:3000

• JBrowse needs a web server; opening index.html directly does not work. The -S flag makes serve follow symlinks, for tracks added with --load symlink.
• Click the sample config to confirm the install works.
• For production, put the folder in your web server's static directory, such as /var/www/html/jbrowse2/.

✕

Do it yourselfIn DesktopSession specIn a notebookWith an agent

The steps behind the figure above, run against your own data.

1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).This figure uses volvox, loaded from a .2bit genome.
2. Type your region of interest into the location box and press Enter.This figure is at ctgA:1-50000.

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

Nothing happens? Paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

Copy

https://jbrowse.org/code/jb2/main/?config=test_data%2Fvolvox%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22volvox%22%2C%22loc%22%3A%22ctgA%3A1-50000%22%7D%5D%7D&sessionName=JBrowse+docs%3A+sample_config

This session spec pastes after &session=spec- on any JBrowse Web instance.

Copy

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:1-50000"
    }
  ]
}

Loaded against config: test_data/volvox/config.json

The same view with jbrowse-anywidget. Point the adapter at your own file.

Copy

from jbrowse_anywidget import LinearGenomeView, make_assembly

view = LinearGenomeView(
    assembly=make_assembly("volvox", "https://your-server/your-genome.fa.gz"),
    location="ctgA:1-50000",
)

view  # display the widget

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file and rerun.

Copy

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:1-50000"
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/volvox/config.json \
  --session session.json -o figure.png

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

Adding tracks#

• The examples run from inside jbrowse2/. To write elsewhere, add --out /var/www/html/jbrowse2, a directory containing config.json or a path to a config file.
• --load copy puts the data file next to config.json so one server serves both; --load symlink links it instead. For data your lab already hosts, pass the URL in place of a path and the track records that URL: jbrowse add-track https://data.myuniversity.edu/rnaseq/sample1.bam.
• The track type and adapter come from the file's extension. Supported file types lists every format and the adapter it maps to, and jbrowse add-track --help the options.

Genome assembly (FASTA)#

samtools faidx genome.fa
jbrowse add-assembly genome.fa --load copy

--name (-n) sets the assembly name, which defaults to the filename. bgzip-compressed indexed FASTA and 2bit work too.

✕

Do it yourselfIn DesktopSession specWith an agent

The steps behind the figure above, run against your own data.

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

Nothing happens? Paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

Copy

https://jbrowse.org/code/jb2/main/?config=test_data%2Fvolvox%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%5D%7D&sessionName=JBrowse+docs%3A+lgv_assembly

This session spec pastes after &session=spec- on any JBrowse Web instance.

Copy

{
  "views": []
}

Loaded against config: test_data/volvox/config.json

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file and rerun.

Copy

cat > session.json <<'JSON'
{
  "views": []
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/volvox/config.json \
  --session session.json -o figure.png

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

BAM / CRAM#

samtools index file.bam   # or file.cram
jbrowse add-track file.bam --load copy

✕

Do it yourselfIn DesktopSession specIn a notebookWith an agent

The steps behind the figure above, run against your own data.

1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).This figure uses volvox, loaded from a .2bit genome.
2. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a CRAM file (.cram + .crai).This figure uses “volvox-sorted.cram (contigA, default display)”.
3. Type your region of interest into the location box and press Enter.This figure is at ctgA:1-20000.

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

Nothing happens? Paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

Copy

https://jbrowse.org/code/jb2/main/?config=test_data%2Fvolvox%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22volvox%22%2C%22loc%22%3A%22ctgA%3A1-20000%22%2C%22tracks%22%3A%5B%22volvox_cram_alignments%22%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+volvox_alignments

This session spec pastes after &session=spec- on any JBrowse Web instance.

Copy

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:1-20000",
      "tracks": [
        "volvox_cram_alignments"
      ]
    }
  ]
}

Loaded against config: test_data/volvox/config.json

The same view with jbrowse-anywidget. Point the adapter at your own file.

Copy

from jbrowse_anywidget import LinearGenomeView, make_assembly

view = LinearGenomeView(
    assembly=make_assembly("volvox", "https://your-server/your-genome.fa.gz"),
    location="ctgA:1-20000",
)

view.add_track({
    "type": "AlignmentsTrack",
    "trackId": "my_track",
    "name": "My track",
    "assemblyNames": ["volvox"],
    "adapter": {"type": "CramAdapter", "uri": "https://your-server/your-file"},
})

view  # display the widget

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file and rerun.

Copy

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:1-20000",
      "tracks": [
        "volvox_cram_alignments"
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/volvox/config.json \
  --session session.json -o figure.png

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

VCF#

A VCF must be bgzip-compressed and tabix-indexed. If tabix reports it unsorted, bcftools sort file.vcf > file.sorted.vcf first.

bgzip file.vcf
tabix file.vcf.gz
jbrowse add-track file.vcf.gz --load copy

✕

Do it yourselfIn DesktopSession specIn a notebookWith an agent

The steps behind the figure above, run against your own data.

1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).This figure uses volvox, loaded from a .2bit genome.
2. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi).This figure uses “volvox 1000genomes vcf”.
3. Type your region of interest into the location box and press Enter.This figure is at ctgA:5000-10000.

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

Nothing happens? Paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

Copy

https://jbrowse.org/code/jb2/main/?config=test_data%2Fvolvox%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22volvox%22%2C%22loc%22%3A%22ctgA%3A5000-10000%22%2C%22tracks%22%3A%5B%22volvox_test_vcf%22%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+volvox_variants

This session spec pastes after &session=spec- on any JBrowse Web instance.

Copy

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:5000-10000",
      "tracks": [
        "volvox_test_vcf"
      ]
    }
  ]
}

Loaded against config: test_data/volvox/config.json

The same view with jbrowse-anywidget. Point the adapter at your own file.

Copy

from jbrowse_anywidget import LinearGenomeView, make_assembly

view = LinearGenomeView(
    assembly=make_assembly("volvox", "https://your-server/your-genome.fa.gz"),
    location="ctgA:5000-10000",
)

view.add_track({
    "type": "VariantTrack",
    "trackId": "my_track",
    "name": "My track",
    "assemblyNames": ["volvox"],
    "adapter": {"type": "VcfTabixAdapter", "uri": "https://your-server/your-file"},
})

view  # display the widget

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file and rerun.

Copy

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:5000-10000",
      "tracks": [
        "volvox_test_vcf"
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/volvox/config.json \
  --session session.json -o figure.png

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

BigWig / BigBed#

No index needed: jbrowse add-track file.bw --load copy.

GFF3 and GTF#

jbrowse sort-gff sorts either format, since GTF shares GFF3's refName and start columns:

jbrowse sort-gff yourfile.gff | bgzip > yourfile.sorted.gff.gz
tabix yourfile.sorted.gff.gz
jbrowse add-track yourfile.sorted.gff.gz --load copy

A plain .gff3 or .gtf loads without any of this, but the whole file is read at once, so sort and index anything genome-scale. How a GTF's per-feature lines become gene models is on Supported file types.

Synteny#

An alignment between two assemblies (PAF, delta, chain, MCScan anchors, MashMap) loads as a synteny track naming both, --assemblyNames query,target. Synteny track covers the formats and minimap2 presets, and Synteny visualization (pairwise minimap2) runs one end to end.

Hosting your own data#

The folder is a static site: plain files a web server hands out unchanged, and the visitor's browser fetches the pieces of each data file it needs. Any web server, S3 or GCS bucket, or institutional file host can serve it (Deploying JBrowse Web). Two properties decide whether a host works, and both fail quietly:

• Byte-range requests. JBrowse reads slices of a BAM, CRAM, BigWig or tabix file, so the host has to answer a Range header with 206 Partial Content. A host returning the whole file with 200 is the usual reason a track that works locally shows nothing in production (Serving data files).
• No re-compression of compressed files. Serving a .bam or .bgz through gzip corrupts the byte offsets the index depends on (Serving data files).

Object storage satisfies both, which is why S3 and GCS are common homes for the data even when the app is served elsewhere. Data on a different domain than the app needs a CORS policy, and data that cannot be public needs authentication.

Indexing feature names for searching#

jbrowse text-index

Indexes the GFF3, GTF and VCF tracks in the config so names can be typed into the location box. Every other track is skipped silently; name one with --tracks and it says why. Text searching covers which attributes are indexed and how to narrow the set.

Tips#

• Subdirectories: jbrowse add-track myfile.bam --subDir my_bams --load copy --out /var/www/html/jbrowse2
• Upgrade JBrowse: jbrowse upgrade /var/www/html/jbrowse2
• Upgrade the CLI: npm install -g @jbrowse/cli
• A second config in the same folder: jbrowse add-assembly mygenome.fa --out /path/to/jbrowse2/alt_config.json --load copy, opened at ?config=alt_config.json

See also#

• User guide
• Config guide
• CLI reference
• FAQ