Using Binder With Quarto
This feature is new in the upcoming Quarto 1.4 release. To use the feature now, you’ll need to download and install the Quarto pre-release.
Overview
The Binder project provides a stack of tools designed to make it easy to share computing environments. When projects use best practices and are hosted online, Binder makes it straightforward to provide users with a link which restores the computing environment.
Quarto can now automatically create supporting files required to permit deployment of Quarto projects using Binder. Use the command quarto use binder
from within a project directory to initialize your directory with required files.
Creating Binder Files
Use the command quarto use binder
from within your Quarto project directory to generate files required to make your project available via Binder. The command will scan the project and based upon the specific configuration (Quarto version and tools, computational engines, data about dependencies and the computational environment), determine the configuration restore the environment.
Files generated by the quarto use binder
command should be committed into your repo so they are available when the repo is used by Binder to restore the computational environment.
Dependencies
When your project is restored to a new computational environment using Binder, any dependencies that the project has must also be restored. There are a few different ways of documenting these dependencies so they may be restored. The most common for the each environment are as follows:
Language | Environment | File |
---|---|---|
R | renv | renv.lock |
Python | Conda | environment.yml |
Python | Pip | requirements.txt |
Julia | Pkg | project.toml |
Configuration Files
The following files may be generated by the command. Note that the command will prompt before overwriting any user files that it didn’t generate or any files that have been modified since they were generated.
postBuild
-
The post build script runs code after restoring the environment. This script is generated with commands required to ensure the proper version of Quarto is present in the environment, install any required tools like TinyTex or Chromium are installed, and to configure VSCode and the Quarto extension for VSCode when applicable.
runtime.txt
-
For R projects, this file will be generated with the appropriate R version, which is used to ensure that the same R version is present in the computational environment. This also will result in RStudio being configured and available when the computational evironment is restored by a user.
install.R
-
For R projects, an
install.R
file will be generated to activate anyrenv
environment that is present. apt.txt
-
Provides a list of Debian packages to install with
apt-get
. This file is generated with all Quarto package dependencies. .jupyter
-
For projects using QMD files with the Jupyter engine, a
.jupyter
directory will be generated which will configure support for VSCode from within the JupyterLab environment.