Wondering what’s next for npm?Check out our public roadmap! »

    @nteract/commuter

    5.11.0 • Public • Published

    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. 🚗 🏢 ✈️ 🗼 🚄 🏬 🚌 🏫 🚲 🌆 🏃 🏡

    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 Variable Description Default
    COMMUTER_STORAGE_BACKEND local, s3, or gcs 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

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

    Environment Variable Description Default
    AWS_ACCESS_KEY_ID Specifies an AWS access key associated with an IAM user or role. Optional
    AWS_SECRET_ACCESS_KEY Specifies the secret key associated with the access key. This is essentially the "password" for the access key. Optional
    AWS_SESSION_TOKEN Specifies the session token value that is required if you are using temporary security credentials. Optional
    AWS_PROFILE Specifies 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 file 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_ENDPOINT S3 endpoint Optional, selected automatically
    COMMUTER_S3_FORCE_PATH_STYLE Set 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 Variable Description Default
    GOOGLE_APPLICATION_CREDENTIALS file path of the JSON file that contains your service account key ""
    COMMUTER_BUCKET GCS bucket name without "gs://" prefix Required
    COMMUTER_GCS_PATH_DELIMITER separator for "paths" "/"
    COMMUTER_GCS_BASE_PREFIX prefix 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:
    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
    

    Tests

    There are three ways you can run tests:

    • If you have your environment set up, you can run tests locally via yarn test.
    • This repository is also set up with GitHub Actions, a builtin CI system, which will automatically trigger test builds for multiple Node versions upon every push into this repository. You can then check out the results in the Actions tab.
    • These GitHub Actions can be triggered locally using act, this way you don't have to have your JavaScript environment set up and you don't have to commit and push in order to run the tests remotely through GitHub.

    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:
    docker run \
    --publish 4000:4000 \
    --mount type=bind,source=/home/username/work/commuter/examples,target=/examples \
    --env COMMUTER_LOCAL_STORAGE_BASEDIRECTORY=/examples \
    commuter:latest
    

    Install

    npm i @nteract/commuter

    DownloadsWeekly Downloads

    33

    Version

    5.11.0

    License

    BSD-3-Clause

    Unpacked Size

    43.8 MB

    Total Files

    1215

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar