com·mut·er

/kəˈmyo͞odər/ a person who travels some distance to work on a regular basis.

As commuters, we rush around from place to place all day. We go to work, school, and stores. We travel to locations near and far. Eventually, we return to our cozy home. 🚗 🏢 ✈️ 🗼 🚄 🏬 🚌 🏫 🚲 🌆 🏃 🏡

Like commuters, our data travels around too. Sometimes we need a notebook at work and other times at a client's site. Wherever and whenever you need your notebooks, commuter has you covered.

What is "commuter"?

As an opinionated nteract focused server, commuter reads notebooks from a local directory or Amazon S3, has a directory explorer to find notebooks, and provides a jupyter compatible version of the contents API. You determine where your notebooks should reside and where they should be shared. Flexibility and convenience.

Try commuter today and take your notebooks wherever you need them.

Demo

Installation

npm install @nteract/commuter-cli -g

Usage

Configure and run commuter with environment variables and commuter server.

Example local run (using a network file share!):

COMMUTER_LOCAL_STORAGE_BASEDIRECTORY=/efs/users/ commuter server

Example S3 run:

COMMUTER_BUCKET=sweet-notebooks commuter server

Environment Variables

General Environment Variables

Environment Variable	Description	Default
COMMUTER_STORAGE_BACKEND	local or s3	local
COMMUTER_DISCOVERY_BACKEND	either elasticsearch or none	"none"
COMMUTER_PORT	Port to run commuter on	4000
COMMUTER_LOCAL_STORAGE_BASEDIRECTORY	directory to serve in local storage mode	process.cwd()
COMMUTER_ES_HOST	ElasticSearch Host	""

Environment Variables for S3 Storage

Environment Variable	Description	Default
COMMUTER_S3_BASE_PREFIX	prefix on the bucket, similar to base directory	""
COMMUTER_S3_PATH_DELIMITER	separator for "paths"	"/"
COMMUTER_BUCKET	bucket contents served from	Required in S3 mode, no default
COMMUTER_S3_KEY	AWS Key	Optional, uses IAM roles or ~/.aws/credentials otherwise
COMMUTER_S3_SECRET	AWS Secret	Optional, uses IAM roles or ~/.aws/credentials otherwise

Roadmap

Details here

Development

Requires Node.js 6+ and npm 3+.

Required env variables

Quick Start

1. git clone git@github.com:nteract/commuter.git
2. cd commuter
3. npm i
4. npm start
5. open http://localhost:3000

Watch mode

For more granular control and automatic reloads run the following in separate terminals:

1. npm run client - browser refresh
2. npm run server:watch - reload express on file changes
3. npm run watch - build lerna components

Notes

In watch mode, the API server (express) runs on port 4000 and the client (webpack dev server) runs on port 3000. For ease of development the webpack dev server proxies requests made on port 3000 to port 4000 (also avoids CORS issues). On production, the server directly renders index.html with bundled static assets.

1. Directory explorer - http://localhost:3000
2. API server - http://localhost:4000/api/contents/<PATH>

Project uses prettier for code formatting (npm run format:code and package.json has more options).

Tests

1. npm test

Deployment

There are few different ways to get commuter deployed on your severs:

From master branch

1. Enter in the terminal:

    git clone git@github.com:nteract/commuter.git
    npm i
    npm start
    open http://localhost:3000
   

2. Currently, the Demo app is deployed on Heroku. Heroku provides a guide for getting started with the heroku CLI which will get you all set up. After all required env variables are set, run:

    git push heroku master
   

From published packages (recommended)

1. Install commuter cli npm install @nteract/commuter-cli -g
2. exec commuter server - the service is typically wrapped inside daemontools

Release

1. npm publish
2. git push --tags

commuter packages

• @nteract/commuter-client
• @nteract/commuter-server
• @nteract/commuter-cli
• @nteract/commuter-breadcrumb
• @nteract/commuter-directory-listing