Skip to content

Usage#

Publish to Posit Connect#

To publish to Posit Connect:

  • Open a Jupyter notebook.
  • Click the blue toolbar icon used for publishing the notebook icon (blue publish button) and select Publish to Posit Connect to publish the current notebook to Posit Connect.

Note

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

Entering server information#

  • If this is your first time publishing a notebook, you will be prompted to enter the location and a nickname for the Posit Connect server.
  • You will also be prompted to enter your API Key. See the Posit Connect User Guide for instructions on generating API Keys for your user.
  • When you click the Add Server button, rsconnect-jupyter will send a request to the Posit Connect server to verify that it can be reached via the requested URL and that the API key is valid.

If your Posit 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 Posit Connect may 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 Posit 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 may select Upload TLS Certificate Bundle to upload the bundle to Jupyter, which will verify your secure connection to Posit 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 Posit Connect will still be encrypted, but you will not be able to verify the identity of the Posit Connect server.

initial dialog that prompts for the location of Posit Connect

Publishing options#

There are three 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 Posit Connect. This enables Posit Connect to recreate the environment and re-run the notebook at a later time.
  • If you select Publish interactive Voila document with source code, your notebook will be published using the Voila package. When visitors view your published notebook, Connect will present it as an interactive application. Voila creates a Jupyter kernel for each visitor so they can interact with any ipywidgets that you have included in your notebook.
  • Selecting Publish finished document only will publish an HTML snapshot of the notebook to Posit Connect. HTML snapshots are static and cannot be scheduled or re-run on the Posit Connect server.

publish dialog

Hide Input#

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

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

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

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

Enable Tags in the 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.

Add the hide_input tag to individual cells

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 may not be made available to users after render.

publish dialog

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 that will be the same as the notebook server environment where jupyter is installed.

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

Generating Manifests for git Publishing#

Posit 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.

Deployment drop-down
menu showing

When you click Create Manifest, one of the following will happen:

  • If a manifest.json or a requirements.txt file does not exist, one will be generated for the current notebook using your current environment.
  • If either file exists, you will be presented with 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.

Dialog titled

For more information on git publishing, see the Posit Connect User Guide.

Handling conflicts#

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

dialog that prompts for overwriting or publishing new content

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

Updating an existing document will not change its publication mode.

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

Clicking the notification will open the published document in the Posit Connect server you selected in the previous dialog.

notification that shows the notebook was published successfully