Integration with Apache Zeppelin

In this section, we will explain how you can seamlessly connect your Apache Zeppelin instances with your ZeppelinHub account.


Download integration library

NOTE : This section is only for Zeppelin-0.5.X users. If you are using Zeppelin-0.6.X or later, you can skip this section.

First of all, you need a library for integration. Please click this download link for the latest version. Then copy your library into lib directory under your ZEPPELIN_HOME ( Apache Zeppelin installation directory ). If you don't have lib folder, just create a new one.


Add a new Apache Zeppelin Instance and Generate a Token

Before we start, if you don't have ZeppelinHub account yet, please read Managing your ZeppelinHub Account and sign up first. Let's start from adding your instances into ZeppelinHub.

After login, you can see a left side menu bar consisting of Spaces & Apache Zeppelin Instances sections.

Click the plus button    and type a instance name and short description for your new instance.

Then, ZeppelinHub will create a Unique Token for you.

Optionally, you can also provide Apache Zeppelin user credentials by checking Include Apache Zeppelin Credentials option.

This feature requires authentication setup on Apache Zeppelin as a prerequisite. But be careful. For security reasons, we do not store your user key. So please make sure that you copied it before closing the popup.

Then you can see the following figure with your instance's token string ( with user key if you provided any user credentials ).

Afterwards, you can see your instance list below Zeppelin Instances section. ZeppelinHub also shows the connection status for each instances.

After adding a new instance, you can manage your instances at Manage Instances tab in the Setting page ( click a down-arrow button at the top ). In this page, you can edit your instances name or delete them from the list.

But be carefull. When deleting a instance in the list, it means that you no longer want to syncronize that instance with ZeppelinHub. So it will also remove all notebooks related to this instance from ZeppelinHub.

You can also add a new instance directly by clicking Orange Circle Button at this page.


Setting Apache Zeppelin environment variables

When you connect a instance to your ZeppelinHub account, you need to set the following environment variables into your ZEPPELIN_HOME/conf/zeppelin-env.sh file. If you don't have this file, you can create it from ZEPPELIN_HOME/conf/zeppelin-env.sh.template.

$ cd ZEPPELIN_HOME/conf
$ cp zeppelin-env.sh.template zeppelin-env.sh

After activating this configuration file, add below three lines to zeppelin-env.sh file. Don't forget to copy your Token generated before.

Below steps are little bit different according to your Apache Zeppelin version. So please check the version first.

Zeppelin-0.5.X

export ZEPPELIN_NOTEBOOK_STORAGE="org.apache.zeppelin.notebook.repo.VFSNotebookRepo, com.nflabs.zeppelinhub.notebook.repo.ZeppelinHubRepo"
export ZEPPELINHUB_API_ADDRESS="ADDRESS_OF_ZEPPELINHUB_SERVICE" (e.g. https://www.zeppelinhub.com)
export ZEPPELINHUB_API_TOKEN="YOUR_TOKEN_STRING"

# With user key if provided
export ZEPPELINHUB_USER_KEY="YOUR_USER_KEY"


Zeppelin-0.6.X or later

export ZEPPELIN_NOTEBOOK_STORAGE="org.apache.zeppelin.notebook.repo.VFSNotebookRepo, org.apache.zeppelin.notebook.repo.zeppelinhub.ZeppelinHubRepo"
export ZEPPELINHUB_API_ADDRESS="ADDRESS_OF_ZEPPELINHUB_SERVICE" (e.g. https://www.zeppelinhub.com)
export ZEPPELINHUB_API_TOKEN="YOUR_TOKEN_STRING"

# With user key if provided
export ZEPPELINHUB_USER_KEY="YOUR_USER_KEY"

As you can see, only ZEPPELIN_NOTEBOOK_STORAGE was updated on Zeppelin-0.6.X. You may also find up-to-date instructions on integrating latest Apache Zeppelin master branch with ZeppelinHub on corresponding Apache Zeppelin documentation website.


Now, start ( or restart ) Apache Zeppelin.

$ cd ZEPPELIN_HOME
$ ./bin/zeppelin-daemon.sh start (or restart)

Then come back to ZeppelinHub and check whether the green light is turned on or not.


Migrating Configurations

If you upgraded Zeppelin-0.5.X to later version, you need to change some configurations in Apache Zeppelin.

1. Remove zeppelinhub-integration-*.jar file under ZEPPELIN_HOME/lib/ directory.

$ rm ZEPPELIN_HOME/lib/zeppelinhub-integration-*.jar

2. From your Zeppelin-0.5.X installation you should have the following variables already set in your ZEPPELIN_HOME/conf/zeppelin-env.sh.

export ZEPPELIN_NOTEBOOK_STORAGE="org.apache.zeppelin.notebook.repo.VFSNotebookRepo, com.nflabs.zeppelinhub.notebook.repo.ZeppelinHubRepo"
export ZEPPELINHUB_API_ADDRESS="ADDRESS_OF_ZEPPELINHUB_SERVICE" (e.g. https://www.zeppelinhub.com)
export ZEPPELINHUB_API_TOKEN="YOUR_TOKEN_STRING"

# With user key if provided
export ZEPPELINHUB_USER_KEY="YOUR_USER_KEY"

Starting from Zeppelin-0.6.0 it is required that the second classname in ZEPPELIN_NOTEBOOK_STORAGE variable to be changed from com.nflabs.zeppelinhub.notebook.repo.ZeppelinHubRepo to org.apache.zeppelin.notebook.repo.zeppelinhub.ZeppelinHubRepo. Thus you need to substitute

export ZEPPELIN_NOTEBOOK_STORAGE="org.apache.zeppelin.notebook.repo.VFSNotebookRepo, com.nflabs.zeppelinhub.notebook.repo.ZeppelinHubRepo"

with

export ZEPPELIN_NOTEBOOK_STORAGE="org.apache.zeppelin.notebook.repo.VFSNotebookRepo, org.apache.zeppelin.notebook.repo.zeppelinhub.ZeppelinHubRepo"

in your ZEPPELIN_HOME/conf/zeppelin-env.sh.

That's all. Then restart Zeppelin.

$ cd ZEPPELIN_HOME
$ ./bin/zeppelin-daemon.sh restart (or start)