Running a Bokeh Server¶

Local or Individual Use¶

One way that you might want to use the Bokeh server is during exploratory data analysis, possibly in a Jupyter notebook. Alternatively, you might want to create a small app that you can run locally, or that you can send to colleagues to run locally. The Bokeh server is very useful and easy to use in this scenario. Both of the methods here below can be used effectively:

• Connecting with bokeh.client

• Building Bokeh Applications

For the most flexible approach, that could transition most directly to a deployable application, it is suggested to follow the techniques in Building Bokeh Applications.

Creating Deployable Applications¶

Another way that you might want to use the Bokeh server is to publish interactive data visualizations and applications that can be viewed and used by a wider audience (perhaps on the internet, or perhaps on an internal company network). The Bokeh Server is also well-suited to this usage, and you will want to first consult the sections:

• Building Bokeh Applications - how to create Bokeh Applications, and then refer to the section

• Deployment Scenarios - how to deploy the Bokeh server with your application.

Shared Publishing¶

Both of the scenarios above involve a single creator making applications on the server, either for their own local use, or for consumption by a larger audience. Another scenario is the case where a group of several creators all want publish different applications to the same server. This is not a good use-case for single Bokeh server. Because it is possible to create applications that execute arbitrary python code, process isolation and security concerns make this kind of shared tenancy prohibitive.

In order to support this kind of multi-creator, multi-application environment, one approach is to build up infrastructure that can run as many Bokeh servers as-needed, either on a per-app, or at least a per-user basis. It is possible that we may create a public service to enable just this kind of usage in the future, and it would also certainly be possible for third parties to build their own private infrastructure to do so as well, but that is beyond the scope of this User’s Guide.

Another possibility is to have a single centrally created app (perhaps by an organization), that can access data or other artifacts published by many different people (possibly with access controls). This sort of scenario is possible with the Bokeh server, but often involves integrating a Bokeh server with other web application frameworks.

Single module format¶

Let’s look again at a complete example and then examine some specific parts in more detail:

# myapp.py

from random import random

from bokeh.layouts import column
from bokeh.models import Button
from bokeh.palettes import RdYlBu3
from bokeh.plotting import figure, curdoc

# create a plot and style its properties
p = figure(x_range=(0, 100), y_range=(0, 100), toolbar_location=None)
p.border_fill_color = 'black'
p.background_fill_color = 'black'
p.outline_line_color = None
p.grid.grid_line_color = None

# add a text renderer to our plot (no data yet)
r = p.text(x=[], y=[], text=[], text_color=[], text_font_size="20pt",
           text_baseline="middle", text_align="center")

i = 0

ds = r.data_source

# create a callback that will add a number in a random location
def callback():
    global i

    # BEST PRACTICE --- update .data in one step with a new dict
    new_data = dict()
    new_data['x'] = ds.data['x'] + [random()*70 + 15]
    new_data['y'] = ds.data['y'] + [random()*70 + 15]
    new_data['text_color'] = ds.data['text_color'] + [RdYlBu3[i%3]]
    new_data['text'] = ds.data['text'] + [str(i)]
    ds.data = new_data

    i = i + 1

# add a button widget and configure with the call back
button = Button(label="Press Me")
button.on_click(callback)

# put the button and plot in a layout and add to the document
curdoc().add_root(column(button, p))

Notice that we have not specified an output or connection method anywhere in this code. It is a simple script that creates and updates objects. The flexibility of the bokeh command line tool means that we can defer output options until the end. We could, e.g., run bokeh json myapp.py to get a JSON serialized version of the application. But in this case, we would like to run the app on a Bokeh server, so we execute:

bokeh serve --show myapp.py

The --show option will cause a browser to open up a new tab automatically to the address of the running application, which in this case is:

http://localhost:5006/myapp

If you have only one application, the server root will redirect to it. Otherwise, You can see an index of all running applications at the server root:

http://localhost:5006/

This index can be disabled with the --disable-index option, and the redirect behavior can be disabled with the --disable-index-redirect option.

In addition to creating Bokeh applications from single python files, it is also possible to create applications from directories.

Directory format¶

Bokeh applications may also be created by creating and populating a filesystem directory with the appropriate files. To start a directory application in a directory myapp, execute bokeh serve with the name of the directory, for instance:

bokeh serve --show myapp

At a minimum, the directory must contain a main.py that constructs a Document for the Bokeh Server to serve:

myapp
   |
   +---main.py

The full set of files that Bokeh server knows about is:

myapp
   |
   +---main.py
   +---server_lifecycle.py
   +---static
   +---theme.yaml
   +---templates
        +---index.html

The optional components are

• A server_lifecycle.py file that allows optional callbacks to be triggered at different stages of application creation, as described in Lifecycle Hooks.

• A static subdirectory that can be used to serve static resources associated with this application.

• A theme.yaml file that declaratively defines default attributes to be applied to Bokeh model types.

• A templates subdirectory with index.html Jinja template file. The directory may contain additional Jinja templates for index.html to refer to. The template should have the same parameters as the FILE template.

Custom variables can be passed to the template via the curdoc().template_variables dictionary in place:

# set a new single key/value
curdoc().template_variables["user_id"] = user_id

# or update multiple at once
curdoc().template_variables.update(first_name="Mary", last_name="Jones")

When executing your main.py Bokeh server ensures that the standard __file__ module attribute works as you would expect. So it is possible to include data files or custom user defined models in your directory however you like. Additionally, the application directory is also added to sys.path so that python modules in the application directory may be easily imported.

An example might be:

myapp
   |
   +---data
   |    +---things.csv
   |
   +---helpers.py
   +---main.py
   |---models
   |    +---custom.js
   |
   +---server_lifecycle.py
   +---static
   |    +---css
   |    |    +---special.css
   |    |
   |    +---images
   |    |    +---foo.png
   |    |    +---bar.png
   |    |
   |    +---js
   |        +---special.js
   |
   |---templates
   |    +---index.html
   |
   +---theme.yaml

In this case you might have code similar to:

from os.path import dirname, join
from helpers import load_data

load_data(join(dirname(__file__), 'data', 'things.csv'))

And similar code to load the JavaScript implementation for a custom model from models/custom.js

Accessing the HTTP Request¶

When a session is created for a Bokeh application, the session context is made available as curdoc().session_context. The most useful function of the session context is to make the Tornado HTTP request object available to the application as session_context.request. Due to an incompatibility issue with the usage of --num-procs only the arguments attribute can be accessed. Attempting to access any other attribute on request will result in an error.

As an example, the following code will access the request arguments to set a value for a variable N (perhaps controlling the number of points in a plot):

# request.arguments is a dict that maps argument names to lists of strings,
# e.g, the query string ?N=10 will result in {'N': [b'10']}

args = curdoc().session_context.request.arguments

try:
  N = int(args.get('N')[0])
except:
  N = 200

Callbacks and Events¶

Before jumping in to callbacks and events specifically in the context of the Bokeh Server, it’s worth discussing different use-cases for callbacks in general.

from functools import partial
from random import random
from threading import Thread
import time

from bokeh.models import ColumnDataSource
from bokeh.plotting import curdoc, figure

from tornado import gen

# this must only be modified from a Bokeh session callback
source = ColumnDataSource(data=dict(x=[0], y=[0]))

# This is important! Save curdoc() to make sure all threads
# see the same document.
doc = curdoc()

@gen.coroutine
def update(x, y):
    source.stream(dict(x=[x], y=[y]))

def blocking_task():
    while True:
        # do some blocking computation
        time.sleep(0.1)
        x, y = random(), random()

        # but update the document from callback
        doc.add_next_tick_callback(partial(update, x=x, y=y))

p = figure(x_range=[0, 1], y_range=[0,1])
l = p.circle(x='x', y='y', source=source)

doc.add_root(p)

thread = Thread(target=blocking_task)
thread.start()

bokeh serve --show testapp.py

from functools import partial
import time

from concurrent.futures import ThreadPoolExecutor
from tornado import gen

from bokeh.document import without_document_lock
from bokeh.models import ColumnDataSource
from bokeh.plotting import curdoc, figure

source = ColumnDataSource(data=dict(x=[0], y=[0], color=["blue"]))

i = 0

doc = curdoc()

executor = ThreadPoolExecutor(max_workers=2)

def blocking_task(i):
    time.sleep(1)
    return i

# the unlocked callback uses this locked callback to safely update
@gen.coroutine
def locked_update(i):
    source.stream(dict(x=[source.data['x'][-1]+1], y=[i], color=["blue"]))

# this unlocked callback will not prevent other session callbacks from
# executing while it is in flight
@gen.coroutine
@without_document_lock
def unlocked_task():
    global i
    i += 1
    res = yield executor.submit(blocking_task, i)
    doc.add_next_tick_callback(partial(locked_update, i=res))

@gen.coroutine
def update():
    source.stream(dict(x=[source.data['x'][-1]+1], y=[i], color=["red"]))

p = figure(x_range=[0, 100], y_range=[0,20])
l = p.circle(x='x', y='y', color='color', source=source)

doc.add_periodic_callback(unlocked_task, 1000)
doc.add_periodic_callback(update, 200)
doc.add_root(p)

Lifecycle Hooks¶

Sometimes it is desirable to have code execute at specific times in a server or session lifetime. For instance, if you are using a Bokeh Server along side a Django server, you would need to call django.setup() once, as each Bokeh server starts, to initialize Django properly for use by Bokeh application code.

Bokeh provides this capability through a set of Lifecycle Hooks. To use these hooks, you must create your application in Directory format, and include a designated file called server_lifecycle.py in the directory. In this file you can include any or all of the following conventionally named functions:

def on_server_loaded(server_context):
    ''' If present, this function is called when the server first starts. '''
    pass

def on_server_unloaded(server_context):
    ''' If present, this function is called when the server shuts down. '''
    pass

def on_session_created(session_context):
    ''' If present, this function is called when a session is created. '''
    pass

def on_session_destroyed(session_context):
    ''' If present, this function is called when a session is closed. '''
    pass

Additionally, on_session_destroyed lifecycle hooks may also be defined directly on the Document being served. Since the task of cleaning up after a user closes a session is common, e.g. to shut down a database connection, this provides an easy route to performing such actions without bundling a separate file. To declare such a callback define a function and register it with the Document.on_session_destroyed method:

doc = Document()

def cleanup_session(session_context):
    ''' This function is called when a session is closed. '''
    pass

doc.on_session_destroyed(cleanup_session)

Standalone Bokeh Server¶

First, it is possible to simply run the Bokeh server on a network for users to interact with directly. Depending on the computational burden of your application code, the number of users, the power of the machine used to run on, etc., this could be a simple and immediate option for deployment an internal network.

However, it is often the case that there are needs around authentication, scaling, and uptime. In these cases, more sophisticated deployment configurations are needed. In the following sections we discuss some of these considerations.

bokeh server

ssh -NfL localhost:5006:localhost:5006 user@remote.host

nohup bokeh server &
ssh -NfR 5006:localhost:5006 user@gateway.host

ssh -NfL localhost:5006:localhost:5006 user@gateway.host

Basic Reverse Proxy Setup¶

If the goal is to serve an web application to the general Internet, it is often desirable to host the application on an internal network, and proxy connections to it through some dedicated HTTP server. This sections provides guidance for basic configuration behind some common reverse proxies.

server {
    listen 80 default_server;
    server_name _;

    access_log  /tmp/bokeh.access.log;
    error_log   /tmp/bokeh.error.log debug;

    location / {
        proxy_pass http://127.0.0.1:5100;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_http_version 1.1;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host:$server_port;
        proxy_buffering off;
    }

}

bokeh serve myapp.py --port 5100

location /static {
    alias /path/to/bokeh/server/static;
}

<VirtualHost *:80>
    ServerName localhost

    CustomLog "/path/to/logs/access_log" combined
    ErrorLog "/path/to/logs/error_log"

    ProxyPreserveHost On
    ProxyPass /myapp/ws ws://127.0.0.1:5100/myapp/ws
    ProxyPassReverse /myapp/ws ws://127.0.0.1:5100/myapp/ws

    ProxyPass /myapp http://127.0.0.1:5100/myapp/
    ProxyPassReverse /myapp http://127.0.0.1:5100/myapp/

    <Directory />
        Require all granted
        Options -Indexes
    </Directory>

    Alias /static /path/to/bokeh/server/static
    <Directory /path/to/bokeh/server/static>
        # directives to effect the static directory
        Options +Indexes
    </Directory>

</VirtualHost>

a2enmod proxy
a2enmod proxy_http
a2enmod proxy_wstunnel
apache2ctl restart

bokeh serve myapp.py --port 5100

Reverse Proxying with Nginx and SSL¶

If you would like to deploy a Bokeh Server behind an SSL-terminated Nginx proxy, then a few additional customizations are needed. In particular, the Bokeh server must be configured with the --use-xheaders flag:

bokeh serve myapp.py --port 5100 --use-xheaders

The --use-xheaders option causes Bokeh to override the remote IP and URI scheme/protocol for all requests with X-Real-Ip, X-Forwarded-For, X-Scheme, X-Forwarded-Proto headers when they are available.

You must also customize Nginx. In particular, you must configure Nginx to send the X-Forwarded-Proto header, as well as configure Nginx for SSL termination. Optionally, you may want to redirect all HTTP traffic to HTTPS. The complete details of this configuration (e.g. how and where to install SSL certificates and keys) will vary by platform, but a reference nginx.conf is provided below:

# redirect HTTP traffic to HTTPS (optional)
server {
    listen      80;
    server_name foo.com;
    return      301 https://$server_name$request_uri;
}

server {
    listen      443 default_server;
    server_name foo.com;

    # add Strict-Transport-Security to prevent man in the middle attacks
    add_header Strict-Transport-Security "max-age=31536000";

    ssl on;

    # SSL installation details will vary by platform
    ssl_certificate /etc/ssl/certs/my-ssl-bundle.crt;
    ssl_certificate_key /etc/ssl/private/my_ssl.key;

    # enables all versions of TLS, but not SSLv2 or v3 which are deprecated.
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;

    # disables all weak ciphers
    ssl_ciphers "ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA:ECDHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES128-SHA256:DHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES256-GCM-SHA384:AES128-GCM-SHA256:AES256-SHA256:AES128-SHA256:AES256-SHA:AES128-SHA:DES-CBC3-SHA:HIGH:!aNULL:!eNULL:!EXPORT:!DES:!MD5:!PSK:!RC4";

    ssl_prefer_server_ciphers on;

    location / {
        proxy_pass http://127.0.0.1:5100;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_http_version 1.1;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host:$server_port;
        proxy_buffering off;
    }

}

This configuration will proxy all incoming HTTPS connections to foo.com to a Bokeh server running internally on http://127.0.0.1:5100.

Load Balancing with Nginx¶

The architecture of the Bokeh server is specifically designed to be scalable—by and large, if you need more capacity, you simply run additional servers. Often in this situation it is desired to run all the Bokeh server instances behind a load balancer, so that new connections are distributed amongst the individual servers.

The Bokeh server is horizontally scalable. To add more capacity, more servers can be run behind a load balancer.¶

Nginx offers a load balancing capability. We will describe some of the basics of one possible configuration, but please also refer to the Nginx load balancer documentation. For instance, there are various different strategies available for choosing what server to connect to next.

First we need to add an upstream stanza to our NGinx configuration, typically above the server stanza. This section looks something like:

upstream myapp {
    least_conn;                 # Use Least Connections strategy
    server 127.0.0.1:5100;      # Bokeh Server 0
    server 127.0.0.1:5101;      # Bokeh Server 1
    server 127.0.0.1:5102;      # Bokeh Server 2
    server 127.0.0.1:5103;      # Bokeh Server 3
    server 127.0.0.1:5104;      # Bokeh Server 4
    server 127.0.0.1:5105;      # Bokeh Server 5
}

We have labeled this upstream stanza as myapp. We will use this name below. Additionally, we have listed the internal connection information for six different Bokeh server instances (each running on a different port) inside the stanza. You can run and list as many Bokeh servers as you need.

You would run the Bokeh servers with commands similar to:

serve myapp.py --port 5100
serve myapp.py --port 5101
...

Next, in the location stanza for our Bokeh server, change the proxy_pass value to refer to the upstream stanza we created above. In this case we use proxy_pass http://myapp; as shown here:

server {

    location / {
        proxy_pass http://myapp;

        # all other settings unchanged
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_http_version 1.1;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host:$server_port;
        proxy_buffering off;
    }

}

Security¶

By default, a Bokeh server will accept any incoming connections on allowed websocket origins. If a session ID is specified, and a session with that ID already exists on the server, then a connection to that session is made. Otherwise, a new session is automatically created and used.

If you are deploying an embedded Bokeh app within a large organization or to the wider internet, you may want to limit who can initiate sessions, and from where. Bokeh has options to restrict session creation.

bokeh serve --show myapp.py

bokeh serve --show --allow-websocket-origin=localhost:5006 myapp.py

bokeh serve --show --allow-websocket-origin=acme:com myapp.py

bokeh serve --show --allow-websocket-origin='*' myapp.py

export BOKEH_SECRET_KEY=`bokeh secret`

BOKEH_SIGN_SESSIONS=yes bokeh serve --allow-websocket-origin=acme.com myapp.py

from bokeh.util.session_id import generate_session_id

script = server_session(url='http://localhost:5006/bkapp',
                        session_id=generate_session_id())
return render_template("embed.html", script=script, template="Flask")

Scaling the server¶

You can fork multiple server processes with the num-procs option. For example, to fork 3 processes:

bokeh serve --num-procs 3

Note that the forking operation happens in the underlying Tornado Server, see notes in the Tornado docs.