How to Publish a Jupyter Notebook to Connect

This guide walks you through creating and publishing a new Jupyter Notebook to Posit Connect.

Prerequisites

Before you begin, you must:

  • Have a compatible version of Python installed on the Connect Server
  • Have the public URL of the Connect server
  • Have a valid Connect account that has been assigned to at least the publisher role
  • Have a working Python installation on the client
  • Have installed the following Python packages:
    • jupyter
    • matplotlib
    • pandas

For more information about requesting permission to publish your content, see the Publishing section of the User Guide.

Step 1. Install the Jupyter Notebook extension

First, install the rsconnect-jupyter package that enables you to publish Jupyter notebooks to Connect.

Permissions

Depending on your environment, root permissions are usually required for system-wide installations which might be necessary to install the rsconnect-jupyter extension. For example, the --sys-prefix flag needs write permissions to the Python installation path.

To do this, the commands might need to be run as root or prefixed with sudo. For example:

sudo pip install rsconnect_jupyter

  • Open a new terminal window and run:

    Terminal
    pip install rsconnect_jupyter
  • Now, you need to enable the Jupyter Notebook extension:

    Terminal
    jupyter-nbextension install --sys-prefix --py rsconnect_jupyter
    jupyter-nbextension enable --sys-prefix --py rsconnect_jupyter
    jupyter-serverextension enable --sys-prefix --py rsconnect_jupyter
  • To verify that the installation was successful, run:

    Terminal
    jupyter notebook
  • If the Jupyter Notebook interface doesn’t automatically display in your browser, then copy and paste the URL(s) provided in the output of your terminal.

Step 2. Create a new Jupyter Notebook

Follow these steps to create a sample notebook to publish to Connect.

  • Open your browser window displaying the main Jupyter Notebook interface, if applicable.

  • At the top of the page, click New, then select Python 3.

    An image of the New drop-down menu

  • Click the title field.

    The title field is located at the top of the page and to the right of the jupyter logo

  • In the Rename Notebook window, give your notebook a name, then click Rename.

    The Rename Notebook window is shown and it also highlights the Rename button

  • In the cell, copy and paste the following:

    import pandas as pd
    dF = pd.read_csv(
        "https://archive.ics.uci.edu/ml/machine-learning-databases/iris/iris.data",
        names=["sl", "sw", "pl", "pw", "class"])
    dF.head()
  • Press Shift + Enter. The first five rows of the dataset display.

    An image displaying the first five rows of the dataset

  • In the new cell, type:

    import matplotlib
    %matplotlib inline
    dF.plot(x="sl", y="sw", kind="scatter")
  • Press Shift + Enter. A scatter plot displays.

    An image displaying the example scatter plot

Step 3. Authorize Jupyter Notebook to publish to Connect

Note

This is a one-time configuration step that is required to publish Jupyter notebooks to Connect.

To publish your notebook to Connect, you need to generate an API key.

  • Navigate and log into Connect.

  • Click your username or profile icon.

    The icon is located in the upper-right corner of your browser page on the Connect navigation/menu bar

  • Click API Keys.

    Once you click your profile, a Profile menu displays. The API Keys option is located under the first option, which is Profile

  • Click + New API Key.

    The NEW API Key button is located on the right side of the page

  • Enter a name for your API key, then click OK.

    The OK button is on the lower-right side of the window

  • To copy your API key, click Copy.

    The Copy button is located under the API key

Step 4. Publish to Connect

  • Return to your Jupyter Notebook that you wish to publish.

  • Click Publish, then select Publish to Connect.

    The button is located on the right side of the menu-button bar

  • Add your Connect Server:

    • In the Server Address field, enter the public URL used to access Connect.

    • In the API Key field, paste the API key that you generated in Connect.

    • In the Server Name field, type a name for your server.

    • If you require an option other than the default Use System TLS Certificates option, then select one of the Secure Connection Settings.

    • Click Add Server.

      This is a screen capture of the Add Connect Server
window

  • In the Publish to Connect window, do the following:

    • In the Publish to field, confirm that your Connect Server Address (the public URL) is correct.

    • Optionally, update the title of your Jupyter Notebook that will display in Connect.

    • Leave the default option for Publish Source Code selected.

    • Click Publish.

      This is an image of the Publish to Connect menu

  • Select the radio button for your notebook and click Next.

    The button is located on the left side of the page and the Next button is located on the lower-right side of the window

  • Click Publish.

    The button is located on the lower-right side of the window

  • At the top of the interface, click the Successfully published content button.

    The button is on the right-side of the menu bar

A Connect browser window opens and displays your published Jupyter Notebook.

Note

Your Jupyter Notebook is running Python code because the Python environment is reconstructed in Connect.

Here is an example of a Jupyter Notebook that was published to Connect:

A screen capture of the notebook that was
published to Connect