Using the rsconnect CLI#
Here's an example command that deploys a Jupyter notebook to Posit Connect,
assuming that you set up a server named
myServer when configuring your account:
rsconnect deploy notebook -n myServer my-notebook.ipynb
Notebook Deployment Options#
There are a variety of options available to you when deploying a Jupyter notebook to Posit Connect.
Including Extra Files#
You can include extra files in the deployment bundle to make them available when your notebook is run by the Posit Connect server. Just specify them on the command line after the notebook file:
rsconnect deploy notebook my-notebook.ipynb data.csv
requirements.txt file exists in the same directory as the notebook file, it will
be included in the bundle. It must specify the package dependencies needed to execute
the notebook. Posit Connect will reconstruct the Python environment using the
specified package list.
If there is no
requirements.txt file or the
--force-generate option is specified,
the package dependencies will be determined from the current Python environment, or
from an alternative Python executable specified via the
--python option or via the
RETICULATE_PYTHON environment variable:
rsconnect deploy notebook --python /path/to/python my-notebook.ipynb
You can see the packages list that will be included by running
pip list --format=freeze yourself,
ensuring that you use the same Python that you use to run your Jupyter Notebook:
/path/to/python -m pip list --format=freeze
Interactive (Voila) Deployment#
By default, Connect renders Jupyter notebooks
into HTML documents. If your notebook includes interactive widgets
ipywidgets), deploy using Voila mode to present the notebook interactively
Interactive mode runs the notebook each time a user visits it, and maintains a live Jupyter kernel so that the user can interact with your code via interactive widgets.
You can run your notebook locally using Voila from the command
voila notebook.ipynb) or via the Voila extension for Jupyter.
Running your notebook locally is helpful to identify issues before deploying.
Notebooks that use
ipywidgets for interactivity can be deployed to Connect.
Other kinds of active content, such as embedded applications and APIs,
are not supported.
When you are ready to deploy an application that you developed in a notebook,
first export the notebook from Jupyter into a separate
using the "File > Export Notebook As… > Executable Script" menu item.
Then deploy the file using
To deploy to Connect:
rsconnect deploy voila my-notebook.ipynb
You can also deploy a directory containing notebooks in Voila mode. Visitors will see a list of notebooks and can select which one to open.
rsconnect deploy voila --multi-notebook ./
Theming and Customization#
You can customize your Voila deployment by including a
in your deployment directory. See the
If you use a custom JupyterLab theme with Voila as described in the
be sure to include the theme package in your
requirements.txt file. This ensures
that Connect installs it in the virtual environment where your
notebook will be run.
Voila automatically spawns a Jupyter kernel when a user visits a deployed Voila notebook. Kernel processes are terminated when the user sessions ends, for example by closing the browser tab. When the user visits the notebook again, Voila will start a new session with a new kernel.
Voila's kernel preheating option enables you to start up one or more Jupyter kernels and execute initialization code before users visit your deployed notebook. Connect may spawn multiple processes to serve user requests, based on the settings in the Runtime tab. Each worker process will have its own set of preheated kernels.
If there are problems executing code in an interactive notebook, Voila
suggests using the
--debug flag to show details about the error. You can
enable Voila debugging in Connect using the
panel. Defining an environment variable named
any non-empty value will enable debugging.
Static (Snapshot) Deployment#
rsconnect deploys the original notebook with all its source code. This
enables the Posit Connect server to re-run the notebook upon request or on a schedule.
If you just want to publish an HTML snapshot of the notebook, you can use the
option. This will cause
rsconnect to execute your notebook locally to produce the HTML
file, then publish the HTML file to the Posit Connect server:
rsconnect deploy notebook --static my-notebook.ipynb
Creating a Manifest for Future Deployment#
You can create a
manifest.json file for a Jupyter Notebook, then use that manifest
in a later deployment. Use the
write-manifest command to do this.
write-manifest command will also create a
requirements.txt file, if it does
not already exist or the
--force-generate option is specified. It will contain the
package dependencies from the current Python environment, or from an alternative
Python executable specified in the
Here is an example of the
rsconnect write-manifest notebook my-notebook.ipynb
Manifests for static (pre-rendered) notebooks cannot be created.