rsconnect-jupyter
User Guide#
rsconnect-jupyter
is a plugin for Jupyter Notebooks that enables publishing notebooks to RStudio Connect.
Requirements#
- Python 3.5.0 and higher
- Jupyter Notebook 5.x
- pip
- wheel
- RStudio Connect v1.7.0 or higher, configured with Python support
Note
If using conda
, pip
and wheel
should already be installed.
Installation#
The installation method depends on the Python environment that you are installing the rsconnect-jupyter
package into.
Note
The rsconnect-jupyter
package is developed for Jupyter Notebook, specifically. Therefore, the package does not work with the JupyterLab development environment.
This documentation covers three methods:
- Installing Jupyter within a virtual environment
- Installing
rsconnect-jupyter
to Jupyter running on RStudio Workbench - Installation in JupyterHub
Please navigate to the installation section below that is best for your environment.
Installing Jupyter within a virtual environment#
To install and use Jupyter within a virtual environment using
virtualenv
, follow the procedures shown below or learn more using the
Virtualenv documentation.
- These commands create and activate a
virtualenv
at/my/path
:Terminal$ pip install virtualenv virtualenv /my/path source /my/path/bin/activate
Tip
Running source /my/path/bin/activate
activates the virtual environment. While the virtualenv
is active, Python-related commands like python
, pip
, and jupyter
will use to copies located inside the virtual environment. You can check which copy of python
you're using by running which python
.
-
Install Jupyter inside the
virtualenv
:Terminal$ pip install jupyter
-
Install rsconnect-jupyter with your virtual environment active to install and activate the plugin for that copy of Jupyter:
-
The following commands should be run after activating the Python environment where you plan to use
jupyter
.-
Install the
rsconnect-jupyter
package with the following command:Terminal$ pip install rsconnect_jupyter
-
Enable the
rsconnect-jupyter
extension with the following commands:Terminal# Install `rsconnect-jupyter` as a jupyter extension jupyter-nbextension install --sys-prefix --py rsconnect_jupyter # Enable JavaScript extension jupyter-nbextension enable --sys-prefix --py rsconnect_jupyter # Enable Python extension jupyter-serverextension enable --sys-prefix --py rsconnect_jupyter
Note
- The above commands only need to be run once when installing
rsconnect_jupyter
. - To deploy content, you will need at least the rsconnect-python package in every kernel you plan to deploy from.
- If you run into an issue during installation, please let us know by filing a bug here.
-
-
Important
Be sure to run Jupyter from this virtual environment, not from
another installation, or the rsconnect-jupyter
extension will
not be available. To do so, you will need to activate the virtual
environment in each new terminal session before you run jupyter
.
Installing to Jupyter running on RStudio Workbench#
-
If you are installing
rsconnect-jupyter
to Jupyter running on RStudio Server Pro, see the RStudio Server Pro documentation on Jupyter Notebooks for instructions on installing the plugin to the right location. -
Once you complete the installation instructions, please return to this document for additional information such as Upgrading or Usage instructions.
Installation in JupyterHub#
In JupyterHub, follow these directions to install the
rsconnect-jupyter
package into the Python environment where the Jupyter
notebook server and kernel are installed:
-
The following commands should be run after activating the Python environment where you plan to use
jupyter
.-
Install the
rsconnect-jupyter
package with the following command:Terminal$ pip install rsconnect_jupyter
-
Enable the
rsconnect-jupyter
extension with the following commands:Terminal# Install `rsconnect-jupyter` as a jupyter extension jupyter-nbextension install --sys-prefix --py rsconnect_jupyter # Enable JavaScript extension jupyter-nbextension enable --sys-prefix --py rsconnect_jupyter # Enable Python extension jupyter-serverextension enable --sys-prefix --py rsconnect_jupyter
Note
- The above commands only need to be run once when installing
rsconnect_jupyter
. - To deploy content, you will need at least the rsconnect-python package in every kernel you plan to deploy from.
- If you run into an issue during installation, please let us know by filing a bug here.
-
Typically those will be the same
environment. If you've configured separate kernel environments, install the
rsconnect-jupyter
package in the notebook server environment as well as each
kernel environment.
The exact install location depends on your JupyterHub configuration.
JupyterHub Example Configuration#
This section presents a simple working example of a JupyterHub configuration
with rsconnect-jupyter
installed.
Docker Example
This example uses Docker, but you can install the rsconnect-jupyter
package in
any Jupyterhub installation. Docker is not required.
Example Dockerfile:
Dockerfile
FROM jupyterhub/jupyterhub:0.9.4
# Install Jupyter notebook into the existing base conda environment
RUN conda install notebook
# Download and install rsconnect-jupyter in the same environment
# Update this to specify the desired version of the rsconnect-jupyter package,
# or pass `--build-arg VERSION=...` to docker build.
ARG VERSION=RSCONNECT_VERSION
ARG REPOSITORY=https://s3.amazonaws.com/rstudio-rsconnect-jupyter
RUN wget ${REPOSITORY}/rsconnect_jupyter-${VERSION}-py2.py3-none-any.whl
RUN pip install rsconnect_jupyter-${VERSION}-py2.py3-none-any.whl && \
jupyter-nbextension install --sys-prefix --py rsconnect_jupyter && \
jupyter-nbextension enable --sys-prefix --py rsconnect_jupyter && \
jupyter-serverextension enable --sys-prefix --py rsconnect_jupyter
# create test users
RUN useradd -m -s /bin/bash user1 && \
useradd -m -s /bin/bash user2 && \
useradd -m -s /bin/bash user3 && \
bash -c 'echo -en "password\npassword" | passwd user1' && \
bash -c 'echo -en "password\npassword" | passwd user2' && \
bash -c 'echo -en "password\npassword" | passwd user3'
CMD ["jupyterhub"]
Run these commands to build and start the container:
Terminal
docker build -t jupyterhub:rsconnect-jupyter .
docker run --rm -p 8000:8000 --name jupyterhub jupyterhub:rsconnect-jupyter
Connect to Jupyterhub on http://localhost:8000 and log in as one of the test users. From there, you can create a notebook and publish it to RStudio Connect. Note that the current Jupyterhub docker image uses Python 3.6.5, so you will need a compatible Python version installed on your RStudio Connect server.