Skip to main content

JBrowse CLI admin server

Caution

We recommend the CLI quickstart for most config setup. The admin-server is a niche tool for occasional GUI editing.

This guide covers configuring JBrowse 2 (adding assemblies and tracks) through the graphical admin interface.

Prerequisites

This tutorial requires the following software:

Starting JBrowse 2 admin server

The JBrowse CLI includes an admin-server tool that serves JBrowse 2 locally and writes any configuration changes back to a config file.

Warning

The admin-server is meant to be used temporarily for configuration, not in production.

The admin-server launches an instance of JBrowse 2 in "admin mode", which then lets you:

  • Add and edit assemblies with the "Assembly manager"
  • Add tracks and edit tracks
  • Add and edit connections

All changes are written to the JBrowse config file (usually config.json). This only works while the admin-server is running.

To start the admin-server, navigate into your JBrowse 2 directory and run:

jbrowse admin-server

This prints a link you can visit in your web browser:

Admin server started on port 9090

To access the admin interface, open your browser to:
http://localhost:9090?adminKey=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

Admin key: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
Config file: /path/to/config.json

To stop the server, press Ctrl+C

Adding a genome assembly

Open the Assembly manager from the menu bar to add an assembly.

This opens a table to create, edit, and delete assemblies in your application:

Screenshot showing the assembly manager, with no assemblies loaded yet. Open this view in JBrowse ↗

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):

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

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

    {
  "views": []
}

    Loaded against config: test_data/empty.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.

    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/empty.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.

    As an example, add the hg38 human reference genome.

    Press Add new assembly, then Open from a URL, and paste the FASTA and its two indexes into the box, one per line:

    https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz
https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz.fai
https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz.gzi

    The form recognizes the three files, pairs the indexes with the FASTA, and fills in a genome name from the filename. That name is editable, and the rest of this page calls the assembly hg38, so set it to that.

    Assembly manager page for adding a new assembly. Open this view in JBrowse ↗

    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):

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

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

      {
  "views": []
}

      Loaded against config: test_data/hg38_only.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.

      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/hg38_only.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.

      A JBrowse with no genome in it getting one: Tools, Assembly manager, Add new assembly, and three URLs pasted into a single box, which the form answers with the adapter it recognized and a name it filled in. Open the session this video starts in ↗

      Submit puts hg38 in the list:

      The assembly manager dialog box with human assemblies available Open this view in JBrowse ↗

      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):

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

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

        {
  "views": []
}

        Loaded against config: test_data/config_demo.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.

        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/config_demo.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.

        Editing a genome assembly

        The pencil icon button in the Assembly manager edits an assembly, and the same table deletes assemblies.

        Adding a track

        Open the Add track form from the menu bar to add a track or connection:

        JBrowse 2 file menu with the 'Add track' form Open this view in JBrowse ↗

        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 hg19, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
        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 GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq genes (hg19)”.
        3. Type your region of interest into the location box and press Enter.This figure is at chr1:1,000,000-1,100,000.

        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):

        https://jbrowse.org/code/jb2/main/?config=test_data%2Fconfig_demo.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg19%22%2C%22loc%22%3A%22chr1%3A1%2C000%2C000-1%2C100%2C000%22%2C%22tracks%22%3A%5B%22ncbi_gff_hg19%22%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+add_track_form

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

        {
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg19",
      "loc": "chr1:1,000,000-1,100,000",
      "tracks": [
        "ncbi_gff_hg19"
      ]
    }
  ]
}

        Loaded against config: test_data/config_demo.json

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

        from jbrowse_anywidget import LinearGenomeView, fetch_hub

view = LinearGenomeView(
    assembly=fetch_hub("hg19"),
    location="chr1:1,000,000-1,100,000",
)

view.add_track({
    "type": "FeatureTrack",
    "trackId": "my_track",
    "name": "My track",
    "assemblyNames": ["hg19"],
    "adapter": {"type": "Gff3TabixAdapter", "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.

        cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg19",
      "loc": "chr1:1,000,000-1,100,000",
      "tracks": [
        "ncbi_gff_hg19"
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/config_demo.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.

        The action button (circular "+") inside the track selector opens the same form:

        The 'Add track' form can be launched from the circular '+' button in the bottom righthand corner Open this view in JBrowse ↗

        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 BAM file (.bam + .bai).This figure uses “volvox-sorted.bam”.
        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):

        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_bam%22%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+add_track_tracklist

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

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

        Loaded against config: test_data/volvox/config.json

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

        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": "BamAdapter", "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.

        cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:1-20000",
      "tracks": [
        "volvox_bam"
      ]
    }
  ]
}
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.

        In the "Add track" form, provide a URL or select a local file to load. For the formats JBrowse supports and their accepted index types, see Supported file types. Plugins add support for further data formats; see the plugin store.

        Editing a track

        Open a Linear Genome View and click the "Select tracks" button. Each track's three-dot (...) menu has a "Settings" button, which opens the configuration editor. The editor live-edits any configurable value for that track, and changes are persisted to the config file when editing through the admin-server.

        Setting a default session

        The graphical admin server also sets the default session, the session that appears when JBrowse 2 is first visited. Open the Set default session form (Admin menu):

        The 'Set default session' will persist your current session into the config file so any subsequent visitors to the app will see this session. Open this view in JBrowse ↗

        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):

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

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

          {
  "views": []
}

          Loaded against config: test_data/empty.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.

          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/empty.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.

          The form clears the default session, or sets it to the currently open session or any previously saved one.

          See also