rgbkrk / kernels-service

:corn: Launch Jupyter Kernels over HTTP

kernels-service

Launch Jupyter kernels over HTTP. Provides only the kernels and kernelspecs APIs of IPython/Jupyter.

Direct launch

kernels.py starts a tornado web server that launches a single kernel and provides the ability to launch more.

Here we set the base path of the IPython API to start at /jupyter/:

$ python kernels.py --base-path=jupyter
[I 150113 14:32:13 kernelmanager:85] Kernel started: a8064a6c-a5a4-45d3-8d50-b226efc10f65
[I 150113 14:32:13 kernels:89] Serving at http://127.0.0.1:8000/jupyter/api/kernels
^C[I 150113 14:32:15 kernels:93] Interrupted...
[I 150113 14:32:16 multikernelmanager:140] Kernel shutdown: a8064a6c-a5a4-45d3-8d50-b226efc10f65

A Docker image is available for launching directly:

$ docker run -it -p 8000:8000 rgbkrk/kernels

Several environment variables are available for configuration:

Environment Variable	Description
KERNEL_NAME	The name of the initial kernel (language type) to use, defaults to system python (could be 'ir' for the R Kernel)

Derivative images of rgbkrk/kernels that install kernels like IJulia or the IRKernel need only define these in their Dockerfiles. ⚠️ Depending on your usage, you may want to include a non-root user in the Docker image that runs the service itself. ⚠️

Options for base path and port are provided via command line arguments (like the tmpnb demo image). If used directly, they must be done with sh -c explicitly:

$ docker run -it -p 8000:8000 rgbkrk/kernels sh -c "/srv/kernels.py --base-path=/krn/"
[I 150113 10:43:00 kernelmanager:85] Kernel started: 83de760b-51d3-420b-a05b-2467439ac45c
[I 150113 10:43:00 kernels:89] Serving at http://127.0.0.1:8000/krn/api/kernels

Otherwise you get that awkward kernel restart that occurs when IPython and Docker's pseudo-exec collide:

$ docker run -it -p 8000:8000 rgbkrk/kernels /srv/kernels.py --base-path=/krn/
[I 150113 10:43:49 kernelmanager:85] Kernel started: c8c3fa7c-3b5b-47f9-b863-cb59cc26ea26
[I 150113 10:43:49 kernels:89] Serving at http://127.0.0.1:8000/krn/api/kernels
[I 150113 10:43:52 restarter:103] KernelRestarter: restarting kernel (1/5)
...

Connecting to the kernel over JavaScript

This is terribly hacky, there must be a better way. I'm directly using one notebook to get access to the kernel running somewhere else.

// Hokey creation of a kernel object
var k = new IPython.Kernel("", "", IPython.notebook);

// This kernel can be located anywhere
k.ws_url = 'ws://127.0.0.1:8000'

// Using the full path provided on launch
k.kernel_url = "/krn/api/kernels/5b7ad625-4484-403a-a7c3-8b16394b2ae7"
k.kernel_id = "5b7ad625-4484-403a-a7c3-8b16394b2ae7"

k.start_channels()

// TODO: Wait for the websocket connection to finalize
k.execute('import os; os.mkdir("touchdown")');

In reality, I want to be able to use the kernel without a notebook.

The reason is that events are propagated to a notebook model in the JavaScript.

kernels-service's Issues

Access-Control-Allow-Origin header is lowercased when kernel-service is accessed via tmpnb / configurable-http-proxy

It seems like the Access-Control-Allow-Origin header is being set to lowercase when it is run through the configurable-http-proxy. Although this is no problem in Chrome, it causes the Safari browser to not recognize the header.

Here's an example. When I access the kernel service over the proxy, not the lower-cased value for Access-Control-Allow-Origin.

http http://jupyter-kernel.odewahn.com:8000/user/pVLZmkH43KTT/api/kernels

HTTP/1.1 200 OK
access-control-allow-origin: *
connection: close
content-length: 67
content-security-policy:
content-type: text/html; charset=UTF-8
date: Wed, 14 Jan 2015 20:03:13 GMT
etag: "93ee31e7d5a26e434153a8cb61633602a0d273cb"
server: TornadoServer/4.0.2
set-cookie: ignored=; expires=Tue, 14 Jan 2014 20:03:13 GMT; Path=/
x-frame-options: SAMEORIGIN

[{"id": "cea89cc0-55a5-42bb-b926-755e5786d8ef", "name": "python2"}]

When I run this directly on the host, though, and bypass the proxy, here's the result. Note that the header is mixed case, which is what is expected:

http 0.0.0.0:50746/user/pVLZmkH43KTT/api/kernels

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Length: 67
Content-Security-Policy:
Content-Type: text/html; charset=UTF-8
Date: Wed, 14 Jan 2015 20:05:04 GMT
Etag: "93ee31e7d5a26e434153a8cb61633602a0d273cb"
Server: TornadoServer/4.0.2
Set-Cookie: ignored=; expires=Tue, 14 Jan 2014 20:05:04 GMT; Path=/
X-Frame-Options: SAMEORIGIN

[{"id": "cea89cc0-55a5-42bb-b926-755e5786d8ef", "name": "python2"}]

Kernel actions result in uncaught exception

I'm trying the various functions on the just_the_kernels branch, and kernel actions (restart or interrupt) seem to be throwing uncaught exceptions. For example, hitting this endpoint:

http://192.168.59.103:8000/api/kernels/27535e31-6b5e-48f0-b493-e92dc5548ac9/restart

Throws this error:

[E 150111 01:57:17 web:931] Uncaught exception in write_error
Traceback (most recent call last):
File "/usr/local/lib/python3.4/dist-packages/tornado/web.py", line 1332, in _execute
result = method(_self.path_args, *_self.path_kwargs)
File "/usr/local/lib/python3.4/dist-packages/tornado/web.py", line 212, in get
raise HTTPError(405)
tornado.web.HTTPError: HTTP 405: Method Not Allowed

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/usr/local/lib/python3.4/dist-packages/tornado/web.py", line 929, in send_error
    self.write_error(status_code, **kwargs)
  File "/usr/local/lib/python3.4/dist-packages/IPython/html/base/handlers.py", line 293, in write_error
    html = self.render_template('%s.html' % status_code, **ns)
  File "/usr/local/lib/python3.4/dist-packages/IPython/html/base/handlers.py", line 234, in render_template
    template = self.get_template(name)
  File "/usr/local/lib/python3.4/dist-packages/IPython/html/base/handlers.py", line 230, in get_template
    return self.settings['jinja2_env'].get_template(name)
KeyError: 'jinja2_env'