Publishing Jupyter Notebooks

Installing the rsconnect-jupyter extension

You must install the rsconnect-jupyter notebook extension and configure your Posit Connect account before attempting to publish from Jupyter Notebook. See the rsconnect-jupyter User Guide for details on how to install the rsconnect-jupyter extension into your Jupyter Notebook environment.

Entering server information

• Open a Jupyter notebook.

• To open the Publishing window, click the blue Publishing icon and select Publish to Posit Connect.

  

• If this is your first time publishing a notebook, follow the prompts to enter the location and a nickname for the Connect server.

• Follow the prompt to enter your API Key. See the API Keys section for instructions on generating API Keys for your user.

• When you click the Add Server button, rsconnect-jupyter sends a request to the Connect server to verify that it can be reached via the requested URL and that the API key is valid.

  

TLS/SSL Settings

If your Connect server was configured with a self-signed certificate (or other certificates that the computer hosting your Jupyter notebook server does not trust), the attempt to contact Connect might fail with a TLS-related error.

You have multiple options in this case, depending on your needs:

1. If your administrator can give you the Certificate Authority (CA) Bundle for your Connect server, ask your administrator if it can be added to the trusted system store.

2. If the CA Bundle cannot be added to the trusted system store, you can select Upload TLS Certificate Bundle to upload the bundle to Jupyter, which will verify your secure connection to Connect.

3. If you cannot obtain the CA bundle, you can disable TLS verification completely by selecting the Disable TLS Certificate Verification check box. Your connection to Connect will still be encrypted, but you will not be able to verify the identity of the Connect server.

Publishing

• Open the notebook you wish to publish.

• Click the blue publishing icon in the notebook toolbar. If the icon is not present, ensure that the plugin is installed and enabled by following the instructions in the rsconnect-jupyter User Guide.

  

• Select Publish to Posit Connect to open the Publishing window.

  

There are two different publication modes:

• If you select Publish document with source code, the notebook file and a list of the Python packages installed in your environment will be sent to Connect. This enables Connect to recreate the environment and re-run the notebook at a later time.

• Selecting Publish finished document only publishes an HTML snapshot of the notebook to Connect. HTML snapshots are static and cannot be scheduled or re-run on the Connect server.

Note

This plugin is only for notebooks using Python kernels. Therefore, R notebooks cannot be published using this plugin.

Environment detection with pip

The list of packages sent along with the notebook comes from the Python environment where the notebook kernel is running. For environment inspection to work, the rsconnect-jupyter package must be installed in the kernel environment. That is, the environment where the ipykernel package is installed. In most cases this is the same as the notebook server environment where jupyter is installed.

The command pip freeze is used to inspect the environment. The output of pip freeze lists all packages currently installed, as well as their versions, which enables Connect to recreate the same environment.

Handling conflicts

If content that matches your notebook’s title is found on Connect, you can choose to overwrite the existing content or create new content.

• Choosing New location creates a new document in Connect.
• You can choose either publication mode:
  • an HTML snapshot or
  • a document with source code

Updating an existing document does not change its publication mode.

Upon successful publishing of the document, a notification is shown in the toolbar.

Clicking the notification opens the published document in the Connect server you selected in the previous dialog.

Publishing options

Hide input

There are two options for hiding input code cells in Jupyter Notebooks published to Connect:

• Hide all input code cells
• Hide only selected input code cells

To hide all input code cells, under the Hide Input section make that selection in the Publish dialog.

To hide only the tagged cells, first enable Tags in the View > Cell Toolbar menu:

Once enabled, tag each cell where you would like to hide the input code. The tag must be named hide_input:

1. Enter hide_input into the text field.

2. Click Add tag to apply the tag to a code cell.

   

Additional files

If your notebook needs some external file to render, add the file using the Select Files… button. You can select any file within the notebook folder. However, these files cannot be made available to users after render.

Generating manifests for git publishing

Connect can poll git repositories for deployable content and update as you add new commits to your repository. To be deployable, a directory must have a valid manifest.json. Python content should also have some kind of environment file (i.e., requirements.txt) to be able to restore the package set in your current environment.

To begin, click the Publish button and select Create Manifest for git Publishing.

When you click Create Manifest, one of the following happens:

• If a manifest.json or a requirements.txt file does not exist, one is generated for the current notebook using your current environment.

• If either file exists, Connect presents a message informing you of this fact. If you need to regenerate the files, delete them in the Jupyter UI or using the console, then repeat this process.

For more information on git publishing, see the Git-Backed Content section.