rsconnect-jupyter User Guide#
rsconnect-jupyter package is a Jupyter Notebook extension (i.e.,
nbextension) that provides publishing compatibility with Posit Connect.
This extension is NOT compatible with JupyterLab. Only Jupyter Notebooks, and associated runtime environments, such as JupyterHub, are supported.
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.
python -m pip install jupyter rsconnect-jupyter
rsconnect-jupyterJupyter Notebook extension.Terminal
python -m jupyter nbextension install --sys-prefix --py rsconnect_jupyter
rsconnect-jupyterJupyter Notebook extensionTerminal
python -m jupyter nbextension enable --sys-prefix --py rsconnect_jupyter
rsconnect-jupyterJupyter Server extension.Terminal
python -m jupyter serverextension enable --sys-prefix --py rsconnect_jupyter
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.
rsconnect-jupyter from Conda Forge.
conda create --name rsconnect-jupyter conda activate rsconnect-jupyter conda install -c conda-forge jupyter rsconnect-jupyter
Next, following the installation guide.
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.
conda create --name rsconnect-jupyter python=3.8
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
Python Virtual Environment (venv)#
python -m venv .venv source .venv/bin/activate
Next, following the installation guide.
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
jupyter, are utilized. To determine which version of
jupyter is active, execute the
which command (e.g,
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.
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.
This configuration is NOT intended for production usage. This is a minmal working configuration designed to highlight
Create the following 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.
docker build -t jupyterhub:rsconnect-jupyter .
Finally, launch the Docker image.
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:
- Open http://localhost:8000 in your browser.
- Login to using the credentials "username" and "password". These credentials match the credentials set in the Dockerfile and may be changed.
- Select the "New" dropdown menu and select "Python 3 (pykernal)".
- Next, follow the usage guide.
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 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.