Note: most of our current development is on JBrowse 2

See

• https://github.com/gmod/jbrowse-components
• https://jbrowse.org/jb2

Note: If you are using plugins or installing from GitHub

You may need to use node <=14 (e.g. node >=15 may fail) due to node-sass not
compiling on newer node versions easily. See
https://github.com/GMOD/jbrowse/pull/1607 for details

2025 update: The latest master branch on GitHub removed node-sass so can be
built with newer versions of node.js e.g. node 22 (not node 23 yet though). You
may need to run export NODE_OPTIONS=--openssl-legacy-provider before
./setup.sh however

Installing JBrowse

To install jbrowse, visit http://jbrowse.org/blog and download the latest
JBrowse zip file. See instructions at http://jbrowse.org/docs/installation.html
for a tutorial on setting up a sample instance.

Install JBrowse from GitHub (for developers)

To install from GitHub, you can simply clone the repo and run the setup.sh
script

git clone https://github.com/GMOD/jbrowse
cd jbrowse
./setup.sh

Develop JBrowse or JBrowse plugins

To obtain a jbrowse development environment, e.g. for jbrowse source code
editing or plugin development (or just running jbrowse from the github repo)

git clone https://github.com/GMOD/jbrowse
cd jbrowse
./setup.sh # not strictly necessary if you don't need to sample data

If you are going to edit the jbrowse source code, then also run

yarn watch

And keep yarn watch running in the background as you create changes to your
code.

To start a temporary dev server, can also run

yarn start

And keep this running in the background, this will launch a webserver running
jbrowse on port 8082.

Alternatively, you can put this jbrowse folder in your webserver (e.g.
/var/www/html/) directory. The key is, if you are modifying jbrowse or plugin
source code, to run yarn watch in the background, so that webpack incorporates
your changes in either the main codebase (src/JBrowse folder) or any plugins
(plugins/YourPlugin).

Note for users in China

In order to make downloads faster you can set a mirror for the npm registry

npm config set registry http://r.cnpmjs.org
npm config set puppeteer_download_host=http://cnpmjs.org/mirrors
export ELECTRON_MIRROR="http://cnpmjs.org/mirrors/electron/"

Notes on setting up a JBrowse server

• If you don't have a webserver such as apache or nginx, you can run
  npm run start and open
  http://localhost:8082/index.html?data=sample_data/json/volvox to see the code
  running from a small express.js server.

• You can alternatively just move the jbrowse folder into a nginx or apache root
  directory e.g. /var/www/html and then navigate to http://localhost/jbrowse

Note: you should avoid using sudo tasks like ./setup.sh and instead use
chown/chmod on folders to your own user as necessary.

Also note: After editing a file, you must re-run the webpack build with
npm run build or you can keep webpack running in "watch" mode by running
npm run watch.

Also also note: by default git clone will clone the master branch which
contains the latest stable release. The latest development branch is called dev.
Run git checkout dev after clone to retrieve this

Installing as an npm module

To install jbrowse from NPM directly, you can run.

npm install @gmod/jbrowse

To setup a simple instance, you can use

node_modules/.bin/jb_setup.js
node_modules/.bin/jb_run.js

Then visit http://localhost:3000/?data=sample_data/json/volvox

Contributing

Looking for places to contribute to the codebase?
Check out the "help wanted" label.

Running the developer test suites

The Travis-CI suite runs Perl, JavaScript, and Selenium automated tests. To run
locally, you can use

prove -Isrc/perl5 -lr tests
node tests/js_tests/run-puppeteer.js http://localhost/jbrowse/tests/js_tests/index.html
pip install selenium nose
MOZ_HEADLESS=1 SELENIUM_BROWSER=firefox JBROWSE_URL='http://localhost/jbrowse/index.html' nosetests

Supported browsers for SELENIUM_BROWSER are 'firefox', 'chrome', 'phantom', and
'travis_saucelabs'. The Sauce Labs + Travis one will only work in a properly
configured Travis CI build environment.

Manual testing

<img style="display: block; margin: 1em auto" src="img/browserstack-logo-600x315.png" width="200" alt="Browserstack"/>

JBrowse has a free open source account on
Browserstack for manual testing. Contact @rbuels for
access.

Generating Packaged Builds

You can also optionally run build steps to create the minimized codebase. Extra
perl dependencies Text::Markdown and DateTime are required to run the build
step.

make -f build/Makefile

To build the Electron app (JBrowse desktop app), run the following

npm install -g electron-packager
make -f build/Makefile release-electron-all

To run the Electron app in debug mode run the following

npm install -g electron
electron browser/main.js

Making a JBrowse release

NOTE: Beginning in 1.12.4,

1. Run
   build/release.sh $newReleaseVersion $nextReleaseVersion-alpha.0 notes.txt,
   where notes.txt is any additional information to add to a blogpost. Then
   check its work, and then run the git push command it suggests to you. This
   makes a tag in the repository for the release, named, e.g. 1.6.3-release.
   This should cause Travis CI to create a release on GitHub under
   https://github.com/GMOD/jbrowse/releases

2. Test that the page loads in IE11 on BrowserStack

3. Add release notes to the new GitHub release that Travis created. Can just
   paste these from release-notes.md, which is in Markdown format.

4. Write a twitter post for usejbrowse and JBrowseGossip with the announcement
   link to the blogpost

5. Write an email announcing the release, sending to gmod-ajax. If it is a major
   release, add gmod-announce and make a GMOD news item.

As you can tell, this process could really use some more streamlining and
automation.