Continuing from the previous blog post, this notebook will explain how to deploy a Bokeh server on Heroku, allowing the world to access the brilliant data visualizations that you've developed using Bokeh. Note- this tutorial was written in May 2017. If you're reading at a much later date, you may need to update the Python and package versions below (and it's possible that Heroku may not support these versions anymore).

The example from this post can be found running here.

To begin, install the Heroku CLI using the instructions found here. The documentation is very helpful, as well.

Open a terminal on your computer and login to Heroku using the command:

heroku login

To create a new Heroku app, use the command:

heroku create appname

Where the appname is the name of your new app. Keep note of what appname you choose, because you'll be using it later in this example for the "--host" parameter.

Now, let's prepare the files and folder structure that will be pushed to Heroku. You'll need "linear_example.py" from the previous post, which can be downloaded $HERE. Make sure it's named exactly "linear_example.py", or the following steps will not work.

We need to define a "runtime.txt" file, which specifies to Heroku which version of Python we want to run. This file must be named exactly "runtime.txt", case sensitive. It should contain the following line:



In [ ]:

    
python-3.6.1

Next, the Python modules which are required to run the Bokeh server must be specified in a file called "requirements.txt", again case sensitive. These will mainly include any imports in the "linear_example.py" code, but I like to specify any dependencies of the imports as well to ensure that the specific version I request is loaded. The release number of the module to load can be specified by "==", or ">=" if "at least" that version is required.

Note that these are likely not the latest release number of these modules, but these are the versions that this particular example was tested on.



In [ ]:

    
bokeh==0.12.4
Jinja2==2.9.5
MarkupSafe==0.23
numpy==1.12.0
pandas==0.19.2
PyYAML==3.12
requests==2.13.0
scikit-learn==0.18.1
scipy==0.18.1
tornado==4.4.2

Finally, a file called "Procfile" tells Heroku how to run our files as a web application. It's essential that the "P" in "Procfile" be capitalized, and that the file does not have an extension. These are two common errors when defining a Procfile.

Our Procfile will contain the following code:



In [ ]:

    
web: bokeh serve --port=$PORT --num-procs=0 --host=linregex.herokuapp.com --address=0.0.0.0 --use-xheaders linear_example.py

Discussion of Procfiles in general are beyond the scope of this post, but let's break down this specific example, piece by piece.

web: tells Heroku that this code should be run as a web server.
bokeh serve may already be familiar to Bokeh users. It starts a Bokeh server using the Python script that is specified later in this line.
--port=$PORT specifies which port should be used for the Bokeh server. Usually, if run locally, you might use something like --port=5005. However, Bokeh sets the port dynamically and stores the current port in the PORT environmental variable, which is being accessed by the Bokeh server automatically here.
--num-procs=0 is used to determine the number of worker processes which may be used for the application. "0" means that the number of workers will automatically be detected based on the available cores.
--host=linregex.herokuapp.com specifies the domain host that the application will be running on. In this case, the domain is the one that I registered on Heroku, but replace with your own Heroku app.
--address=0.0.0.0 tells Bokeh that the IP address will be assigned dynamically.
--use-xheaders tells Bokeh that it should use the xheaders for determining the network protocols. This parameter is required when running Bokeh on Heroku, but not when running a Bokeh server locally.
linear_example.py is the name of the Python script that the Bokeh server should run.

Now we're ready to deploy our example on Heroku. Create a new directory (preferably somewhere on your computer where it's easily accessible and will stick around for a while) containing the four files from above:

linear_example.py
runtime.txt
requirements.txt
Procfile

Open a command terminal on your computer, navigate to the directory where the above four files are stored, and run the following commands. A git tutorial is beyond the scope of this blog post, but some basic descriptions of what is happening after each command is provided.

git init

First, we initialize a git repository in the folder. Heroku requires that all applications be deployed using a git repository.

git add .

This command adds all the files in the directory to the next commit to the git repository.

git commit -m 'initial'

The next command will actually commit the files to the repository. 'initial' is a comment that provides information about what the commit contains.

git push heroku master

Finally, we push the git repository to the Heroku server. When this command is run, Python 3.6 and the modules in the requirements.txt file will be installed on the Heroku app, which may take some time.

If no errors are encountered, you can view your app on the web using:

heroku open