Integrating Posit Workbench with Jupyter Notebooks on a Single Server#
Overview#
These steps describe how to integrate Posit Workbench, formerly RStudio Workbench, with Jupyter Notebooks running on a single server.
This integration makes use of the Launcher in Workbench to spawn Jupyter Notebook and JupyterLab sessions on a single node without the use of an external resource manager.
Info
Launcher is a new feature of RStudio Workbench 1.2 that is only available under named user licensing. RStudio Workbench 1.2 without Launcher is available under existing server-based licensing. For questions about using Launcher with Workbench, please contact sales@posit.co.
Prerequisites#
This integration is intended to be performed on top of a base installation of Workbench.
Step 1. Configure Workbench with Launcher#
-
Add the following lines to the Workbench configuration file:
File: /etc/rstudio/rserver.conf# Launcher Config launcher-address=127.0.0.1 launcher-port=5559 launcher-sessions-enabled=1 launcher-default-cluster=Local launcher-sessions-callback-address=http://127.0.0.1:8787
-
In the
launcher-sessions-callback-address
setting, you should change the protocol and port if you are using HTTPS or a different port for Workbench.
Step 2. Configure Launcher settings and plugins#
-
Add the following lines to the Launcher configuration file:
File: /etc/rstudio/launcher.conf[server] address=127.0.0.1 port=5559 server-user=rstudio-server admin-group=rstudio-server authorization-enabled=1 thread-pool-size=4 enable-debug-logging=1 [cluster] name=Local type=Local
-
Now that you have updated the file, you must restart the RStudio Server service:
Terminal$ sudo rstudio-server restart
-
Once you have restarted RStudio Server, run the following command to restart the Launcher service:
Terminal$ sudo rstudio-launcher restart
Step 3. Install Python#
- Use the Install Python steps to install the
following on the server:
-
Python,
pip
Info
Our recommended installation instructions for Python allow you to make multiple versions of Python available and avoid replacing existing versions of Python when updating system packages.
-
Step 4. Install Jupyter Notebooks, JupyterLab, and Python packages#
-
From the previous step, you should still have the
PYTHON_VERSION
environment variable defined with the version of Python that you installed. If not, then do then you can define this environment variable before proceed by running the following command and replacing3.7.13
with the version of Python that you are using:Terminal$ export PYTHON_VERSION=3.7.13
-
Install Jupyter Notebooks, JupyterLab, and the notebook extensions for Workbench and Connect:
Terminal$ sudo /opt/python/${PYTHON_VERSION}/bin/pip install jupyter jupyterlab rsp_jupyter rsconnect_jupyter workbench_jupyterlab
-
Install and enable the Jupyter Notebook extensions:
Terminal$ sudo /opt/python/${PYTHON_VERSION}/bin/jupyter-nbextension install --sys-prefix --py rsp_jupyter $ sudo /opt/python/${PYTHON_VERSION}/bin/jupyter-nbextension enable --sys-prefix --py rsp_jupyter $ sudo /opt/python/${PYTHON_VERSION}/bin/jupyter-nbextension install --sys-prefix --py rsconnect_jupyter $ sudo /opt/python/${PYTHON_VERSION}/bin/jupyter-nbextension enable --sys-prefix --py rsconnect_jupyter $ sudo /opt/python/${PYTHON_VERSION}/bin/jupyter-serverextension enable --sys-prefix --py rsconnect_jupyter
Step 5. Configure Launcher with Jupyter Notebooks#
-
Add the following lines to the Launcher Jupyter configuration file:
File: /etc/rstudio/jupyter.confjupyter-exe=/opt/python/3.7.13/bin/jupyter notebooks-enabled=1 labs-enabled=1 default-session-cluster=Local
- If you installed a version other than Python 3.7.13, then you can replace
3.7.13
in the abovejupyter-exe
setting with the the version of Python that you installed.
- If you installed a version other than Python 3.7.13, then you can replace
Step 6. Restart Workbench and Launcher Services#
-
Run the following to restart services:
Terminal$ sudo rstudio-server restart $ sudo rstudio-launcher restart
Step 7. Test Workbench with Launcher and Jupyter Notebooks#
- From your browser, navigate to the Workbench interface and log in.
- Select New Session and do the following:
- Give your session a name.
- In the **Editor** field, select either Jupyter Notebooks or JupyterLab as the IDE.
- Click Start Session.
Now, you can use the Jupyter Notebooks or JupyterLab interfaces.
Important
Some local Jupyter configurations may prevent the JupyterLab session from correctly launching in Workbench. For example, setting a password in the files ~/.jupyter/jupyter-server-config.json
or ~/jupyter/jupyter-server-config.py
, will cause the JupyterLab session to start but not load through the Workbench interface. Commenting out the configuration in question is sufficient to restore expected functionality.
(Optional) Configure multiple Python versions or environments#
The Python integration steps described above result in a single Python environment that contains both core packages for Jupyter Notebooks as well as Python packages for end users.
While this is a simple approach, this setup can result in issues if end users want to use different versions of the same package or if some packages conflict with core packages for Jupyter Notebooks.
If you would like to use multiple versions of Python or different Python environments, or if you want to install Jupyter Notebook in a separate environment from Python packages for end users, then you can refer to the documentation for using multiple Python versions and environments with Jupyter.
Troubleshooting Workbench and Jupyter#
Refer to the support article on troubleshooting Jupyter Notebooks in Workbench for additional information on troubleshooting Workbench with Jupyter.
Additional Documentation#
For more information on Workbench and Jupyter Notebooks, reference the Jupyter section in the Workbench Administration Guide.