Recipe: Setup a Local Pendo Docker Container to Run a Jupyter Notebook

note: This Docker container includes the latest version of Ubuntu (18.04 as of Sept 4, 2018), Python, matplotlib, pandas, word cloud and Jupyter Notebook.

Overview

Pendo Technical Account Management (TAM) team leverages Jupyter Notebooks to interactively run a collection of API calls against a given Pendo subscription, page(s), feature(s) and guide(s). These notebooks will cover the following use cases:

note: Download this Pendo Helper file and save it in the local folder that contains all of your Jupyter Notebooks. This Helper file is called within a Jupyter Notebook to help format your JSON outputs.

This recipe covers how to install the Docker container to easily run a provided Jupyter notebook locally. To run a notebook, you will need a Jupyter Notebook server environment. To take care of most of the heavy-lifting in creating your own environment, the TAM team created this Docker container that you can leverage to run a Jupyter Notebook server locally and run the sample Jupyter Notebooks.

note: All of the Docker commands in this readme were tested on a MacBook Pro running OS X High Sierra v10.13.6. The commands were later tested on OS X Mojave v 10.14. If you’re using Windows or Linux as your local environment, you might have to alter the Docker commands per Docker’s documentation.

Ingredients (What Do I Need?)

If you don’t already have Docker installed locally, download the software:
- For Mac users: Docker Stable Download
- For Windows users: Download from Docker Store
- Linux users: See Docker documentation
Download the sample Jupyter Notebook(s) you wish to use and a Helper file. Be sure to place all downloads in a folder locally
Your Pendo Integration API key
- If you don’t have this feature, please contact your Customer Success Manager (CSM) and inquire about purchasing the Integration API package

How to Make It

For users who don’t already have Docker installed:

Step A. Create a Docker user account and install Docker on your machine using the software you just downloaded. After installing, follow Docker’s validation steps to make sure you have a good install.

Step B. Once you complete your Docker installation, continue with the following steps to start the Pendo Jupyter Notebook server container.

For users who already have Docker installed:

Step 1. Run the Pendo Jupyter Notebook server container by typing this command prompt in terminal (or command line):

note: Be sure to replace the highlighted portion /Your/Notebook/Directory/Here/Notebooks with the full file path where you saved your library of notebooks in Step B.

If you were successful running this, you should see something like the following:

Step 2. Within the above message, note the URL at the bottom. Copy & paste that into a browser being certain to remove the container ID (Example from above: 7df29163416f) and the surrounding parenthesis before you submit the URL to open Jupyter Notebook.

Your resulting URL should look something like this: http://127.0.0.1:8888/?token=Your_Token_ID_Here

note: The token value will change every time you stop and start a Jupyter Notebook, so be sure to copy the entire URL every time you stop or start the Jupyter Notebook server, modify to remove the container ID, then submit to run.

Step 3. You should now see the Jupyter Notebook interface in your browser and all your notebooks in the notebooks directory you mounted in the Docker run command.

Step 4. Select the Jupyter Notebook you would like to run by double-clicking on it. Follow the prompts to run the notebook.

About the Container

The container is ephemeral - its only job is to serve Jupyter Notebooks. Any notebook changes you make and save will be written to the notebook(s) in your local notebooks directory. They’re persistent.

How to Quit or Stop the notebook server

If you want to quit or halt the notebook server, you can click Quit in the interface, or, from the command line (which has been co-opted by Jupyter Notebook) press Control+c twice.

Options:

You can run your container in the background by adding the -d parameter to the docker run command: docker run -it -d -p 8888:8888 -v /Your/Notebook/Directory/Here/Notebooks:/home/jupyter pendo-notebook
If you run your container in the background, to get the URL for it, type docker ps to get the id for the running container then type docker logs CONTAINER_ID_or_NAME_HERE.
To stop the container, you can use Quit in Jupyter Notebooks, or you can use docker stop CONTAINER_ID_or_NAME_HERE. Run docker ps again and you shouldn’t see the container running.
If you don’t want to use this container, you can use a minimal version of it created and maintained by the Jupyter project. It can be run without additional parameters like mounting a local notebooks directory by typing docker run jupyter/minimal-notebook. To start Jupyter Notebook using this container, copy/paste the URL in a browser then modify the URL as described above.
You can also run this minimal build with the same parameters used in the full build. The run command will look like this docker run -it -p 8888:8888 -v /Your/Notebook/Directory/Here/Notebooks:/home/jovyan jupyter/minimal-notebook

Analytics