No description, website, or topics provided.
briehl Merge pull request #1408 from briehl/uploader-help
SCT-1370 Show how to link an account to Globus
Latest commit baf8e87 Sep 24, 2018
Failed to load latest commit information.
docker Grrr...missing paren Jun 28, 2018
docs add instructions for updating the base image Aug 30, 2018
kbase-extension Merge pull request #1408 from briehl/uploader-help Sep 24, 2018
narrbase-image update the base image Aug 30, 2018
nbextensions Merge pull request #1387 from briehl/SCT-1219-multi-output Aug 30, 2018
scripts have container build script fetch from dockerhub if it can Sep 19, 2018
src modify help text in dropzone area Sep 22, 2018
test Merge pull request #1408 from briehl/uploader-help Sep 24, 2018
.bowerrc Renamed 'components' to 'ext_components' Dec 18, 2015
.coveragerc added coverage config file Oct 25, 2017
.eslintrc.yml let's insist on strict to help clean up code! [SCT-804] Apr 12, 2018
.gitignore cleanup Jun 12, 2018
.gitmodules final? all gone? needs testing. Oct 11, 2016
.travis.yml add clustergrammer install to travis add pillow (sklearn dep) sklearn… Aug 28, 2018
DEPENDENCIES Add kbase-ui to DEPENDENCIES Jan 15, 2016
Dockerfile update the base image Aug 30, 2018
Dockerfile2 Build small narrative version server and push May 31, 2018
Gruntfile.js update build directive to handle ES2015 better Jul 27, 2018 update known issues. Feb 17, 2016 Create Jun 12, 2014
Makefile Patch config.json when running tests to get rid of dev_mode template … Aug 8, 2018 Merge remote-tracking branch 'origin' into sprint-2018Q1S4 Apr 5, 2018 bump version to 3.8.2, add release notes Aug 30, 2018
bower.json bump version to 3.8.2, add release notes Aug 30, 2018 Redo of the headless branch Oct 19, 2016
kbase-logdb.conf Added logging conf file, updated deploy script. Aug 4, 2014
narrative-log-proxy.conf Added sanitized config file for the log proxy. Oct 13, 2014
narrative_object.spec Fix problem with copying not updating the workspace pointer correctly. Jan 30, 2016
package.json bump version to 3.8.2, add release notes Aug 30, 2018
tox.ini Redo of the headless branch Oct 19, 2016

The KBase Narrative Interface


Branch Status
master Build Status Coverage Status
develop Build Status Coverage Status

This is the repository for the KBase Narrative Interface.


The KBase Narrative Interface builds on the Jupyter Notebook and contains elements to interact with various KBase tools and data stores.

This document contains links to various documentation in the docs directory, with a brief description of each.

Local Installation (for developers)

Short version: Requires the following:

  • Python 2.7+ (working on updating to Python 3...)
  • Node.js v6 LTS (needed for npm)
  • Bower
git clone
cd narrative
./scripts/ -v narr-venv
source narr-venv/bin/activate

Long version:

Local Narrative setup/deployment

Server installation (for administrators)

If you want to set up your own Narrative server that uses the Docker framework, the below document will walk you through it. Once the server is set up, you only need to pull new code and build a new Docker image from it. You can also pull Narrative images directly from Dockerhub in the KBase namespace.

The document specifically describes how you would build the system on a Vagrant image, but is applicable to any Ubuntu-based system.

Production Narrative setup/deployment Dockerhub Narrative builds


In progress!

The Narrative sits on top of the Jupyter Notebook, so most of its architecture is a mirror of that. However, the Narrative's interaction with other KBase elements - namely the data stores and job running services - merits its own description. This will be ongoing (and evolving!), but a brief description of how a job gets run and registered is available here:

Narrative App/Method Running

When deployed in production, the Narrative Interface is compiled into a Docker container. When a user logs in, they have their own instance provisioned for them through an Nginx proxy, which provides a temporary server-side Narrative environment only for that user. Any changes made to a Narrative get saved as part of KBase data stores, but any changes to the file system or the Narrative kernel (e.g. local variables) are lost when the user logs out and their Docker instance gets shut down.


Testing is composed of three components:

  • a make test directive that runs through a batch of unit-testing of the Narrative, both the front-end Javascript-based components, and the back-end IPython modifications
  • a travis.yml file for Travis-CI testing
  • a set of Selenium-based end-to-end tests that simulate browser interactions

Testing locally (i.e. not through Travis-CI) requires a local Narrative installation, with active virtualenv (if installed that way). Then just run make test or make test-frontend-unit or make test-backend. If you haven't changed any configuration, this will run unauthenticated tests and skip any tests that require authentication.

To run authenticated tests, you'll need to get an auth token from KBase servers, drop it in a file in the test directory (as the only line in that file), then modify two config files. These are test/unit/testConfig.json for frontend tests, and src/biokbase/narrative/tests/test.cfg for backend tests [TODO: merge those, or move them somewhere sensible]. The frontend test file should have the "token" block modified to include your username and the path to the token file. The backend test file should be updated so that the test_user and/or private_user keys in the [users] and [token_files] block are aligned (e.g. users.test_user is the user for the token in token_files.test_user).

Note: DO NOT CHECK YOUR TOKEN FILE IN TO GITHUB. You'll be shamed mercilessly.

Submitting code

We currently use a modified version of the famous Git flow workflow, described below:

Narrative Git Workflow

The short version is this - all development work is done on the develop branch. After some stability occurs, this gets merged to staging for internal testing, then to master where it is tagged and released to production.

So when you want to submit code, please make a pull request against develop.