Using pip¶

We make stable releases of the kernel gateway to PyPI. You can use pip to install the latest version along with its dependencies.

# install from pypi
pip install jupyter_kernel_gateway

Once installed, you can use the jupyter CLI to run the server.

# run it with default options
jupyter kernelgateway

Using jupyter/minimal-kernel¶

The docker-stacks project defines a minimal-kernel Docker image. The Dockerfile for this image installs the kernel gateway and sets it as the default container command. You can run an instance of this container with the following commands:

docker pull jupyter/minimal-kernel
docker run -it --rm -p 8888:8888 jupyter/minimal-kernel

Using another docker-stacks image¶

You can add the kernel gateway to any docker-stacks image to get a more feature-filled kernel environment. For example, you could define a Dockerfile like so:

# start from the jupyter image with R, Python, and Scala (Apache Toree) kernels pre-installed
FROM jupyter/all-spark-notebook

# install the kernel gateway
RUN pip install jupyter_kernel_gateway

# run kernel gateway on container start, not notebook server
EXPOSE 8888
CMD ["jupyter", "kernelgateway", "--KernelGatewayApp.ip=0.0.0.0", "--KernelGatewayApp.port=8888"]

You can then build and run it.

docker build -t my/kernel-gateway .
docker run -it --rm -p 8888:8888 my/kernel-gateway

HTTP Resources¶

The HTTP API consists of kernel, session, monitoring, and metadata resources. All of these are documented in a swagger.yaml file. You can use the Swagger UI to interact with a running instance of the kernel gateway by pointing the tool to the /api/swagger.json resource.

Websocket Resources¶

The /api/kernels/{kernel_id}/channels resource multiplexes the Jupyter kernel messaging protocol over a single Websocket connection.

See the NodeJS and Python client demos for two simple examples of using these resources to send code to kernels for interactive evaluation.

Getting the Request Data¶

Before the gateway invokes an annotated cell, it sets the value of a global notebook variable named REQUEST to a JSON string containing information about the request. You may parse this string to access the request properties.

For example, in Python:

# GET /hello/world
req = json.loads(REQUEST)
# do something with req

You may specify path parameters when registering an endpoint by prepending a : to a path segment. For example, a path with parameters firstName and lastName would be defined as the following in a Python comment:

# GET /hello/:firstName/:lastName

The REQUEST object currently contains the following properties:

• body - The value of the body, see the [Body And Content Type](#Request Content-Type and Request Body Processing) section below
• args - An object with keys representing query parameter names and their associated values. A query parameter name may be specified multiple times in a valid URL, and so each value is a sequence (e.g., list, array) of strings from the original URL.
• path - An object of key-value pairs representing path parameters and their values.
• headers - An object of key-value pairs where a key is a HTTP header name and a value is the HTTP header value. If there are multiple values are specified for a header, the value will be an array.

Setting the Response Body¶

The response from an annotated cell may be set in one of two ways:

1. Writing to stdout in a notebook cell
2. Emitting output in a notebook cell

The first method is preferred because it is explicit: a cell writes to stdout using the appropriate language statement or function (e.g. Python print, Scala println, R print, etc.). The kernel gateway collects all bytes from kernel stdout and returns the entire byte string verbatim as the response body.

The second approach is used if nothing appears on stdout. This method is dependent upon language semantics, kernel implementation, and library usage. The response body will be the content.data structure in the Jupyter execute_result message.

In both cases, the response defaults to status 200 OK and Content-Type: text/plain if cell execution completes without error. If an error occurs, the status is 500 Internal Server Error. If the HTTP request method is not one supported at the given path, the status is 405 Not Supported. If you wish to return custom status or headers, see the next section.

See the api_intro.ipynb notebook for basic request and response examples.

Setting the Response Status and Headers¶

Annotated cells may have an optional metadata companion cell that sets the HTTP response status and headers. Consider this Python cell that creates a person entry in a database table and returns the new row ID in a JSON object:

# POST /person
req = json.loads(REQUEST)
row_id = person_table.insert(req['body'])
res = {'id' : row_id}
print(json.dumps(res))

Now consider this companion cell which runs after the cell above and sets a custom response header and status:

# ResponseInfo GET /hello/world
print(json.dumps({
    "headers" : {
        "Content-Type" : "application/json"
    },
    "status" : 201
}))

Currently, headers and status are the only fields supported. headers should be an object of key-value pairs mapping header names to header values. status should be an integer value. Both should be printed to stdout as JSON.

Given the two cells above, a POST request to /person produces a HTTP response like the following from the kernel gateway, assuming no errors occur:

HTTP/1.1 200 OK
Content-Type: application/json

{"id": 123}

See the setting_response_metadata.ipynb notebook for examples of setting response metadata.

Swagger Spec¶

The resource /_api/spec/swagger.json is automatically generated from the notebook used to define the HTTP API. The response is a simple Swagger spec which can be used with the Swagger editor, a Swagger ui, or with any other Swagger-aware tool.

Currently, every response is listed as having a status of 200 OK.

Running¶

The minimum number of arguments needed to run in HTTP mode are --KernelGatewayApp.api=notebook-http and --KernelGatewayApp.seed_uri=some/notebook/file.ipynb.

If you development, you can run the kernel gateway in notebook-http mode using the Makefile in this repository:

make dev ARGS="--KernelGatewayApp.api='notebook-http' \
--KernelGatewayApp.seed_uri=/srv/kernel_gateway/etc/api_examples/api_intro.ipynb"

With the above Make command, all of the notebooks in etc/api_examples are mounted into /srv/kernel_gateway/etc/api_examples/ and can be run in HTTP mode.

The notebook-http mode will honor the prespawn_count command line argument. This will start the specified number of kernels and execute the seed_uri notebook on each one. Requests will be distributed across the pool of prespawned kernels, providing a minimal layer of scalability. An example which starts a pool of 5 kernels follows:

make dev ARGS="--KernelGatewayApp.api='notebook-http' \
    --KernelGatewayApp.seed_uri=/srv/kernel_gateway/etc/api_examples/api_intro.ipynb" \
    --KernelGatewayApp.prespawn_count=5

I can’t access kernel gateway in my Docker container.¶

The kernel gateway server listens on port 8888 by default. Make sure this internal port is exposed on an external port when starting the container. For example, if you run:

docker run -it --rm -p 9000:8888 jupyter/minimal-kernel

you can access your kernel gateway on the IP address of your Docker host an port 9000.

Kernel gateway raises an error when I use notebook-http mode.¶

The notebook-http mode publishes a web API defined by annotations and code in a notebook. Make sure you are specifying a path or URL of a notebook (*.ipynb) file when you launch the kernel gateway in this mode. Set the --KernelGatewayApp.seed_uri command line parameter or KG_SEED_URI environment variable to do so.

Prerequisites¶

Install docker and docker-machine on your system. Create and activate a Docker VM for development.

docker-machine create -d virtualbox dev
eval "$(docker-machine env dev)"

Clone the repo¶

Clone this repository in a local directory that your local Docker VM can volume mount:

# make a directory under ~ to put source
mkdir -p ~/projects
cd !$

# clone this repo
git clone https://github.com/jupyter/kernel_gateway.git

Build the development image¶

Build a Docker image containing additional dev libraries.

make image

Run the tests¶

Run the tests suites under Python 2 and 3.

make test-python3
make test-python2

Run the gateway server¶

Run an instance of the kernel gateway server.

make dev

To access the running server:

1. Run docker-machine ls and note the IP of the dev machine.
2. Visit http://THAT_IP:8888/api in your browser where THAT_IP is the IP address returned from the previous step.

Build the docs¶

Run Sphinx to build the HTML documentation.

make docs

Update the Swagger API spec¶

After modifying any of the APIs in jupyter-websocket mode, you must update the project’s Swagger API specification.

1. Load the current swagger.yaml file into the Swagger editor.
2. Make your changes.
3. Export both the swagger.json and swagger.yaml files.
4. Place the files in kernel_gateway/services/api.
5. Add, commit, and PR the changes.

0.5¶

0.5.0 (2016-04-08)¶

• Support multiple cells per path in notebook-http mode
• Add a Swagger specification of the jupyter-websocket API
• Add KERNEL_GATEWAY=1 to all kernel environments
• Support environment variables in POST /api/kernels
• numpydoc format docstrings on everything
• Convert README to Sphinx/ReadTheDocs site
• Convert ActivityManager to a traitlets LoggingConfigurable
• Fix base_url handling for all paths
• Fix unbounded growth of ignored kernels in ActivityManager
• Fix caching of Swagger spec in notebook-http mode
• Fix failure to install due to whitespace in setup.py version numbers
• Fix call to kernel manager base class when starting a kernel
• Fix test fixture hangs

0.4¶

0.3¶

0.2¶

0.1¶