Integration with Apache Zeppelin

In this section, we will explain how you can create a Apache Zeppelin space in ZEPL and seamlessly connect it with your Apache Zeppelin instance.

Create a Zeppelin Instance Space

Click "New Space" button in the main page to create a new Space and check "External Repository". Then select the Zeppelin from the dropdown menu.

Once created, ZEPL should provide a Unique Token which will can be used when you connect ZEPL with your Apache Zeppelin instance.

To edit the space's information such as name & description or to delete the space, open a dialog using Edit space located in top-right corner of the page.

Be cautious when deleting an Apache Zeppelin space. Deleting the space will stop synchronization with Apache Zeppelin and will remove all notebooks, not only from ZEPL, but also from all shared spaces in ZEPL.


Connect ZEPL with Apache Zeppelin

Setting Apache Zeppelin environment variables

Preparation For Linux, OSX

When you connect a space to your ZEPL 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.

Preparation For Windows

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

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

After activating this configuration file, add below three lines to zeppelin-env.cmd 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.

(Deprecated) Zeppelin-0.5.X for Linux, OSX

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

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.zepl.com)
export ZEPPELINHUB_API_TOKEN="YOUR_TOKEN_STRING"

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


Zeppelin-0.6.X for Linux, OSX

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.zepl.com)
export ZEPPELINHUB_API_TOKEN="YOUR_TOKEN_STRING"

Zeppelin-0.6.X for Windows

set ZEPPELIN_NOTEBOOK_STORAGE=org.apache.zeppelin.notebook.repo.VFSNotebookRepo, org.apache.zeppelin.notebook.repo.zeppelinhub.ZeppelinHubRepo
set ZEPPELINHUB_API_ADDRESS=https://www.zepl.com
set ZEPPELINHUB_API_TOKEN=YOUR_TOKEN_STRING


Zeppelin-0.7.x single user for Linux, OSX

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


Zeppelin-0.7.x single user for Windows

set ZEPPELIN_NOTEBOOK_STORAGE=org.apache.zeppelin.notebook.repo.GitNotebookRepo, org.apache.zeppelin.notebook.repo.zeppelinhub.ZeppelinHubRepo
set ZEPPELINHUB_API_ADDRESS=https://www.zepl.com
set ZEPPELINHUB_API_TOKEN=YOUR_TOKEN_STRING


Zeppelin-0.7.x multiple users on Zeppelin server for Linux, OSX

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

You may have noticed that you don't need ZEPPELINHUB_API_TOKEN in this scenario, and instead you can login with your ZEPL account, as described in the next section.

In this case your token will be automatically recognized from your space information and default one will be loaded. In order to login with your ZEPL credentials, you will need to complete the steps in the next section.

You may also find up-to-date instructions on integrating latest Apache Zeppelin master branch with ZEPL on corresponding Apache Zeppelin documentation website.


Login to Apache Zeppelin 0.7.x with ZEPL credentials

Starting from 0.7.x release Apache Zeppelin has added more multi-user support functionality, so we made it possible to login to Zeppelin with ZEPL credentials in case multiple users use same Zeppelin server. For better experience with integration we recommend you to use the latest release of 0.7.x branch (e.g. 0.7.1).

After you set the environment variables mentioned in the previous section, first you'll need to modify your conf/shiro.ini security configuration file. If you don't have this file, you can create it from ZEPPELIN_HOME/conf/shiro.ini.template.

$ cd ZEPPELIN_HOME/conf
$ cp shiro.ini.template shiro.ini

Then you'll need to modify the section under ### A sample for configuring ZeppelinHub Realm as below

#### A sample for configuring ZeppelinHub Realm
zeppelinHubRealm = org.apache.zeppelin.realm.ZeppelinHubRealm

### Url of ZeppelinHub
zeppelinHubRealm.zeppelinhubUrl = service_url
securityManager.realms = $zeppelinHubRealm

note that instead of service_url you should have URL of your ZEPL service (e.g. https://www.zepl.com).

It completes this section by letting you login to Zeppelin with your ZEPL account credentials.


Start Apache Zeppelin daemon


Finally, start (or restart) Apache Zeppelin.

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

Return to ZEPL. An indicator should indicate whether Zeppelin is properly connected.


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.zepl.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)

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