The proxied Jupyter tool is a useful place to develop code and analyses in a notebook style. Ghub users can easily share their notebooks with other users by publishing notebooks as tools. The publication process is described in Publishing Jupyter Notebooks.
These instructions take you through testing the deploy of a Jupyter notebook based tool. Here, we'll assume that the short name for your tool is toolname. To test the notebook tool, it's handy to use Ghub's Workspace10 tool, since this allows you to fully test the deploy in the context of the Hub.
1. Create the tool
Once you have your notebook working to your satisfaction on Ghub, you next create the tool to house it, as described in Publishing Jupyter Notebooks, and edit the invoke script. Once this is done, it is time to test.
2. Test invoke the tool
From the Workspace10 tool, or the Jupyter terminal tool, navigate to the directory where your tool's repo is located. For a tool you've called toolname and stored in the apps subdirectory of your home, this will be something like:
Now, navigate to your tool's middleware directory, and call the invoke script for your tool, by typing:
cd middleware ./invoke
Check the command line output to determine the success of your tool invoke call. Errors will display here if a problem is encountered. Use these to aid in your troubleshooting. If you see errors, you will need to revisit the tool sources, retesting to see if your fixes have worked, before going on with this procedure. Note that you may also see warnings displayed, as well as informational output. Neither warnings nor information indicate issues that need to be fixed.
A successful invoke script call will output in part:
The Jupyter notebook is running
...followed by a lengthy URL that reads, in part:
Congratulations, your notebook-based tool is now running!
3. Check the running notebook
In the Workspace10 tool's command line output, note the informational output, denoted by lines starting in "I", and warning output, denoted by lines starting in "W", that is also displayed. These messages can be ignored safely; refer to the figure below.
Within the Workspace10 tool, you can now start a browser and paste into it the URL of the running Jupyter kernel. This test is not possible from outside your development environment, in order to protect your unreleased tool.
Copy the running kernel's URL
First, locate and highlight the kernel URL provided in the output from the invoke script:
Start the Workspace10 browser
Start the Firefox browser from the Workspace10 tool's menu. To do so, click the black button at the bottom left of the Workspace10 and access the Firefox menu item, as shown in this graphic:
Navigate to the running kernel
A browser window will display, running inside your Workspace10 tool session on Ghub. Finally, click (mouse wheel or both mouse buttons) to paste the running Jupyter kernel's URL into the browser navigation bar, as shown in this graphic:
Now, the Workspace10 browser will display the running tool. This is the notebook running as a tool, and should be a good indication of how the tool will run once it is deployed.
One important error type you should watch for is the URL timeout. If there are URLs that your notebook needs access to in order to run, they will likely time out during this test. Collect any such URLs and include them in a support ticket to Ghub administrators. The administrator will need to whitelist these URLs in order for them to be accessible to your notebook once it is a deployed tool. Be sure to explain this in your ticket, and clearly identify the tool name and the reason each URL is needed.
To stop testing, close the browser session running inside your Workspace10, then type "control-c" in the terminal where you called the invoke script. Once the prompt returns, your notebook kernel has stopped.
You can make any adjustments needed to the underlying code before you flag your tool as Uploaded and continue with the deployment process outlined in the Publishing Jupyter Notebooks page.