Rewrites the installation guide

rstudio · Feb 23, 2023 · 1272f29 · 1272f29
1 parent e230923
commit 1272f29
Show file tree

Hide file tree

Showing 7 changed files with 147 additions and 126 deletions.
diff --git a/docs/docs/index.md b/docs/docs/index.md
@@ -1,143 +1,134 @@
 # `rsconnect-jupyter` User Guide
 
-`rsconnect-jupyter` is a plugin for Jupyter Notebooks that enables publishing notebooks to Posit Connect.
+The `rsconnect-jupyter` package is a _Jupyter Notebook_ extension (i.e., `nbextension`) that provides publishing compatiblity with [Posit Connect](https://docs.posit.co/rsc/#rstudio-connect).
 
 ## Requirements
 
-- Python 3.5.0 and higher
-- Jupyter Notebook 5.x
-- [pip](https://pypi.org/project/pip/)
-- [wheel](https://pypi.org/project/wheel/)
-- [Posit Connect](https://www.posit.co/download/posit-connect/) v1.7.0 or higher, configured with Python support
+- [Python >=3.7](https://www.python.org/downloads/)
+- [Jupyter](https://pypi.org/project/jupyter)
+- [Posit Connect](https://www.posit.co/download/posit-connect/**) v1.7.0 or higher, configured with Python support
 
-!!! note
-    If using `conda`, `pip` and `wheel` should already be installed.
+!!! Warning
+    This extension is **NOT** compatible with _JupyterLab_. Only _Jupyter Notebooks_, and associated runtime enviornments, such as _JupyterHub_, are supported.
 
-## Installation
-
-The installation method depends on the Python environment that you are installing the `rsconnect-jupyter` package into.
+!!! Warning
+    In order to publish to _Posit Connect_, a compatible Python environment must in exist on the _Post Connect_ instance. See the _Posit Connect_ documentation on [Python integrations](https://docs.posit.co/rsc/integration/python/) for additional information.
 
-!!! note
-    The `rsconnect-jupyter` package is developed for Jupyter Notebook, specifically. Therefore, the package does not work with the JupyterLab development environment.
+## Installation
 
-This documentation covers three methods:
+--8<-- "snippets/install.md"
 
-- [Installing Jupyter within a virtual environment](#installing-jupyter-within-a-virtual-environment)
-- [Installing `rsconnect-jupyter` to Jupyter running on Posit Workbench](#installing-to-jupyter-running-on-posit-workbench)
-- [Installation in JupyterHub](#installing-in-jupyterhub)
+## Runtime Environment Configuration
 
-Please navigate to the installation section below that is best for your environment.
+### Localhost (Your Computer)
 
-### Installing Jupyter within a virtual environment
+For localhost installation, a Python virtual environment is recommend to isolate runtime dependencies. There are various Python virtual environments avaiable. The following tutorial covers a few of them.
 
-To install and use Jupyter within a virtual environment using
-`virtualenv`, follow the procedures shown below or learn more using the
-[Virtualenv](https://virtualenv.pypa.io/en/latest/) documentation.
+#### Conda
 
-- These commands create and activate a `virtualenv` at `/my/path`:
-  <div class="code-title">Terminal</div>
-  ```bash
-  $ pip install virtualenv
-  virtualenv /my/path
-  source /my/path/bin/activate
-  ```
+Install `rsconnect-jupyter` from [Conda Forge](https://conda-forge.org).
 
-!!! 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`.
+<div class="code-title">Terminal</div>
+```shell
+conda create --name rsconnect-jupyter
+conda activate rsconnect-jupyter
+conda install -c conda-forge jupyter rsconnect-jupyter
+```
 
-- Install Jupyter inside the `virtualenv`:
-  <div class="code-title">Terminal</div>
-  ```bash
-  $ pip install jupyter
-  ```
+Next, following the [installation guide](#installation).
 
-- Install rsconnect-jupyter with your virtual environment active to install and activate the plugin for that copy of Jupyter:
+!!! Tip
+    When creating a _Conda_ virtual environment, a specific Python version may be specified. Create your virtual environment with a Python environment that is avaiable on your Posit Connect server.
 
-    --8<-- "snippets/python_pkg.md"
+    <div class="code-title">Terminal</div>
+    ```shell
+    conda create --name rsconnect-jupyter python=3.8
+    ```
 
-!!! 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`.
+#### Python Virtual Environment (virtualenv)
 
----
+<div class="code-title">Terminal</div>
+```shell
+python -m pip install virtualenv
+python -m virtualenv .venv
+source .venv/bin/activate
+```
 
-### Installing to Jupyter running on Posit Workbench
+Next, following the [installation guide](#installation).
 
-- If you are installing `rsconnect-jupyter` to Jupyter running on RStudio Server Pro, see
-the [RStudio Server Pro documentation on Jupyter Notebooks](https://docs.rstudio.com/rsp/integration/jupyter-standalone/#4-install-jupyter-notebooks-jupyterlab-and-python-packages)
-for instructions on installing the plugin to the right location.
+!!! Tip
+    Running `source .venv/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.
 
-- Once you complete the installation instructions, please return to this document for additional information such as [Upgrading](upgrading) or [Usage](usage) instructions.
+### Posit Workbench
 
----
+See [Installing Python on Posit Workbench](https://docs.posit.co/rsw/integration/jupyter-standalone/#4-install-jupyter-notebooks-jupyterlab-and-python-packages).
 
-### Installation in JupyterHub
+Once you complete the installation instructions, please return to this document for additional information such as [Upgrading](upgrading) or [Usage](usage) instructions.
 
-In JupyterHub, follow these directions to install the
-`rsconnect-jupyter` package into the Python environment where the Jupyter
-notebook server and kernel are installed:
+## JupyterHub
 
---8<-- "snippets/python_pkg.md"
+Follow the [installation guide](#installation) to install `rsconnect-jupyter` onto the _JupyterHub_ server.
 
-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.
+If you've configured separate kernel environments, repeat the installation guide for each kernel environment.
 
-The exact install location depends on your JupyterHub configuration.
+!!! Note
+    The exact install location depends on your JupyterHub configuration.
 
-#### JupyterHub Example Configuration
+#### Quick Start Example
 
-This section presents a simple working example of a JupyterHub configuration
-with `rsconnect-jupyter` installed.
+The following example shows how to launch a Docker container running _JupyterHub_ with the `rsconnect-jupyter` extension installed.
 
-??? example "Docker Example"
-    This example uses Docker, but you can install the `rsconnect-jupyter` package in
-    any Jupyterhub installation. Docker is not required.
+!!! example "Docker Example"
 
-    Example Dockerfile:
+    Create the following Dockerfile.
 
     <p class="code-title">Dockerfile</p>
     ```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"]
+    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"]
     ```
 
-    Run these commands to build and start the container:
+    Next, build the `Dockerfile` to create a new Docker image named jupyterhub:rsconnect-jupyter.
 
     <p class="code-title">Terminal</p>
-    ```bash
+    ```shell
     docker build -t jupyterhub:rsconnect-jupyter .
+    ```
+
+    Finally, launch the Docker image.
+
+    <p class="code-title">Terminal</p>
+    ```shell
     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 Posit Connect.
-    Note that the current Jupyterhub docker image uses Python 3.6.5, so you will
-    need a compatible Python version installed on your Posit Connect server.
+    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](http://localhost:8000) in your browser.
+    1. Login to using the credentials "username" and "password". These credentials match the credentials set in the Dockerfile and may be changed.
+    1. Select the "New" dropdown menu and select "Python 3 (pykernal)".
+    1. Next, follow the [usage guide](./usage).
+
+    !!! 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.
diff --git a/docs/docs/snippets/install.md b/docs/docs/snippets/install.md
@@ -0,0 +1,28 @@
+1. Install `jupyter` and `rsconnect-jupyter`.
+
+    <div class="code-title">Terminal</div>
+    ``` shell
+    python -m pip install jupyter rsconnect-jupyter
+    ```
+
+1. Install the `rsconnect-jupyter` _Jupyter Notebook_ extension.
+
+    <div class="code-title">Terminal</div>
+    ```shell
+    python -m jupyter nbextension install --sys-prefix --py rsconnect_jupyter
+    ```
+
+1. Enable the `rsconnect-jupyter` _Jupyter Notebook_ extension
+
+    <div class="code-title">Terminal</div>
+    ```shell
+    python -m jupyter nbextension enable --sys-prefix --py rsconnect_jupyter
+    ```
+
+1. Enable the `rsconnect-jupyter` _Jupyter Server_ extension.
+
+    <div class="code-title">Terminal</div>
+    ```shell
+    python -m jupyter serverextension enable --sys-prefix --py rsconnect_jupyter
+    ```
+
diff --git a/docs/docs/snippets/python_pkg.md b/docs/docs/snippets/python_pkg.md
diff --git a/docs/docs/upgrading.md b/docs/docs/upgrading.md
@@ -6,4 +6,4 @@ Follow the procedures below to upgrade `rsconnect-jupyter`.
     --8<-- "snippets/uninstall.md"
 
 - Then, reinstall it.
-    --8<-- "snippets/python_pkg.md"
+    --8<-- "snippets/install.md"
diff --git a/examples/jupyterhub/Dockerfile b/examples/jupyterhub/Dockerfile
@@ -0,0 +1,20 @@
+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"]
diff --git a/examples/jupyterhub/justfile b/examples/jupyterhub/justfile
@@ -0,0 +1,7 @@
+PORT := "8000"
+
+build:
+  docker build -t jupyterhub:rsconnect-jupyter .
+
+start:
+  docker run --rm -p {{PORT}}:8000 --name jupyterhub jupyterhub:rsconnect-jupyter
diff --git a/setup.cfg b/setup.cfg
@@ -25,6 +25,6 @@ install_requires =
 setup_requires =
     setuptools
 packages = rsconnect_jupyter
-python_requires = >=3.5
+python_requires = >=3.7
 include_package_data = true
 zip_safe = false