Home

Awesome

Glitch Deployed styled with prettier

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. :car: :office: :airplane: :tokyo_tower: :bullettrain_side: :department_store: :bus: :school: :bike: :city_sunset: :runner: :house_with_garden:

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.

commuter

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

Installation

You may use whichever package manager (npm or yarn) best suits your workflow. The nteract team internally uses yarn.

npm install @nteract/commuter -g
# OR
yarn global add @nteract/commuter

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

Example S3 run:

COMMUTER_BUCKET=sweet-notebooks commuter

Environment Variables

General Environment Variables

Environment VariableDescriptionDefault
COMMUTER_STORAGE_BACKENDlocal, s3, or gcslocal
COMMUTER_DISCOVERY_BACKENDeither elasticsearch or none"none"
COMMUTER_PORTPort to run commuter on4000
COMMUTER_LOCAL_STORAGE_BASEDIRECTORYdirectory to serve in local storage modeprocess.cwd()
COMMUTER_ES_HOSTElasticSearch Host""

Environment Variables for S3 Storage

Authentication to S3 is using CredentialProviderChain with default providers. This supports the most common ways of authenticating in AWS.

Environment VariableDescriptionDefault
AWS_ACCESS_KEY_IDSpecifies an AWS access key associated with an IAM user or role.Optional
AWS_SECRET_ACCESS_KEYSpecifies the secret key associated with the access key. This is essentially the "password" for the access key.Optional
AWS_SESSION_TOKENSpecifies the session token value that is required if you are using temporary security credentials.Optional
AWS_PROFILESpecifies the name of the profile with the credentials and options to use. This can be the name of a profile stored in a credentials or config filedefault
COMMUTER_S3_BASE_PREFIXprefix on the bucket, similar to base directory""
COMMUTER_S3_PATH_DELIMITERseparator for "paths""/"
COMMUTER_BUCKETbucket contents served fromRequired in S3 mode, no default
COMMUTER_S3_ENDPOINTS3 endpointOptional, selected automatically
COMMUTER_S3_FORCE_PATH_STYLESet to true to activate s3ForcePathStyle. Forces path-style URLs for s3 objects, therefore URLs will be in the form <endpoint>/<bucket>/<key> instead of <bucket>.<endpoint>/<key>false

Environment Variables for Google Storage

Environment VariableDescriptionDefault
GOOGLE_APPLICATION_CREDENTIALSfile path of the JSON file that contains your service account key""
COMMUTER_BUCKETGCS bucket name without "gs://" prefixRequired
COMMUTER_GCS_PATH_DELIMITERseparator for "paths""/"
COMMUTER_GCS_BASE_PREFIXprefix on the bucket, similar to base directory""

Roadmap

ROADMAP Document

Development

Quick Start

  1. git clone git@github.com:nteract/commuter.git
  2. cd commuter
  3. yarn
  4. yarn dev
  5. open http://localhost:4000

Dev Docker

A Dockerfile for a local dev server can be use as follows:

  1. docker build --tag commuter:dev --file Dockerfile.dev .
  2. Run this:
<pre> docker run \ --init \ --interactive \ --tty \ --rm \ --publish 4000:4000 \ --mount type=bind,source=(pwd),target=/app \ --env COMMUTER_LOCAL_STORAGE_BASEDIRECTORY=/app/examples \ commuter:dev </pre>

Tests

There are three ways you can run tests:

Deployment

  1. Install commuter cli yarn add @nteract/commuter
  2. exec commuter - the service is typically wrapped inside daemontools

Deployment (Docker / Kubernetes)

A Dockerfile intended for Production use (suitable for Kubernetes or other container runtime) has been contributed. Instructions are below.

Note: there is no officially published Docker image at this time, you should publish it to your own image registry.

  1. Build and tag image docker build --tag commuter:latest .
  2. Image can be executed as follows:
<pre> docker run \ --publish 4000:4000 \ --mount type=bind,source=/home/username/work/commuter/examples,target=/examples \ --env COMMUTER_LOCAL_STORAGE_BASEDIRECTORY=/examples \ commuter:latest </pre>