rsconnect-jupyter User Guide

The rsconnect-jupyter package is a Jupyter Notebook extension (i.e., nbextension) that provides publishing compatibility with Posit Connect.

Requirements

• Python >=3.7
• Jupyter
• Notebook >=5,7
• Posit Connect (supported versions)

Warning

This extension is NOT compatible with JupyterLab. Only Jupyter Notebooks, and associated runtime environments, such as JupyterHub, are supported.

Warning

In order to publish to Posit Connect, a compatible Python environment must in exist on the Posit Connect instance. See the Posit Connect documentation on Python integrations for additional information.

Installation

1. Install jupyter and rsconnect-jupyter.

   Terminal

   python -m pip install jupyter rsconnect-jupyter
   

2. Install the rsconnect-jupyter Jupyter Notebook extension.

   Terminal

   python -m jupyter nbextension install --sys-prefix --py rsconnect_jupyter
   

3. Enable the rsconnect-jupyter Jupyter Notebook extension

   Terminal

   python -m jupyter nbextension enable --sys-prefix --py rsconnect_jupyter
   

4. Enable the rsconnect-jupyter Jupyter Server extension.

   Terminal

   python -m jupyter serverextension enable --sys-prefix --py rsconnect_jupyter
   

Environment Configuration

Localhost (Your Computer)

For localhost installation, a Python virtual environment is recommended to isolate runtime dependencies. There are various Python virtual environments available. The following tutorial covers a few of them.

Conda

Install rsconnect-jupyter from Conda Forge.

Terminal

conda create --name rsconnect-jupyter
conda activate rsconnect-jupyter
conda install -c conda-forge jupyter rsconnect-jupyter

Next, following the installation guide.

Tip

When creating a Conda virtual environment, a specific Python version may be specified. Create your virtual environment with a Python environment that is available on your Posit Connect server.

Terminal

conda create --name rsconnect-jupyter python=3.8

Note

If Anaconda is used, then Jupyter Notebook launches with kernel environments for each existing Conda environment. Follow the installation guide for each kernel/Conda-environment to enable rsconnect-jupyter.

Python Virtual Environment (venv)

Terminal

python -m venv .venv
source .venv/bin/activate

Next, following the installation guide.

Tip

Running source .venv/bin/activate activates the virtual environment. While the virtual environment is active, the .venv/bin directory is prepended to the $PATH environment variable for the active shell. Therefore executables installed within the virtual environment, like python, pip, and jupyter, are utilized. To determine which version of python, pip, or jupyter is active, execute the which command (e.g, which python).

JupyterHub

Follow the installation guide to install and enable rsconnect-jupyter in JupyterHub.

If you've configured separate kernel environments, repeat the installation guide for each kernel environment.

Note

The exact install location depends on your JupyterHub configuration.

Quick Start Example

The following example shows how to launch a Docker container running JupyterHub with the rsconnect-jupyter extension installed.

Warning

This configuration is NOT intended for production usage. This is a minmal working configuration designed to highlight rsconnect-jupyter configuration.

Docker Example

Create the following Dockerfile.

Dockerfile

FROM jupyterhub/jupyterhub:3

# Install Jupyter and the rsconnect-jupyter extension
RUN python3 -m pip install jupyter rsconnect-jupyter

# Enables the rsconnect-jupyter extension
RUN python3 -m jupyter nbextension install --sys-prefix --py rsconnect_jupyter
RUN python3 -m jupyter nbextension enable --sys-prefix --py rsconnect_jupyter
RUN python3 -m jupyter serverextension enable --sys-prefix --py rsconnect_jupyter

# Create a new user called "username" with the password "password"
#
# Use these credentials when logging into JupyterHub.
#
# Example:
#     username: "username"
#     password: "password"
RUN useradd -m -p $(openssl passwd -1 password) -s /bin/sh username

ENTRYPOINT ["jupyterhub"]

Next, build the Dockerfile to create a new Docker image named jupyterhub:rsconnect-jupyter.

Terminal

docker build -t jupyterhub:rsconnect-jupyter .

Finally, launch the Docker image.

Terminal

docker run --rm -p 8000:8000 --name jupyterhub jupyterhub:rsconnect-jupyter

Once executed, a series of startup logs will be shown. Wait for the log message: JupyterHub is now running at http://:8000.

Once shown, the JupyterHub server is running on your local machine. To access JupyterHub procceed with the following steps:

1. Open http://localhost:8000 in your browser.
2. Login to using the credentials "username" and "password". These credentials match the credentials set in the Dockerfile and may be changed.
3. Select the "New" dropdown menu and select "Python 3 (pykernal)".
4. Next, follow the usage guide.

Warning

At the time of writing, the jupyterhub/jupyterhub:3 Docker image is built using Python version 3.10.6. Therefore, in order to publish to Posit Connect, a compatible Python version 3.10 environment must exist in Posit Connect.

Posit Workbench

Posit Workbench supports Jupyter Notebook sessions. See the Jupyter Configuration guide to configure Jupyter Notebook sessions.

Once enabled, follow the installation guide to install and enable the rsconnect-jupyter plugin for each Jupyter kernel.