Voilà

https://voila.readthedocs.io/en/stable
Admin
Voilà allows you to convert a Jupyter Notebook into an interactive dashboard that allows you to...
Tokens:28,805
Snippets:183
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Run Example Notebooks with Voilà

Source: https://voila.readthedocs.io/en/stable/using

Navigates to the notebooks directory and starts the Voilà server to render the example notebooks.

```shell
cd notebooks/
voila
```

--------------------------------

### Install Additional Libraries for Examples

Source: https://voila.readthedocs.io/en/stable/_sources/using.md

Install necessary libraries like ipywidgets, ipyvolume, and bqplot using conda to run the example notebooks provided with Voilà. This ensures all dependencies for interactive examples are met.

```bash
conda install -c conda-forge ipywidgets ipyvolume bqplot scipy
```

--------------------------------

### Install Example Notebook Dependencies

Source: https://voila.readthedocs.io/en/stable/using

Installs required libraries for running the example notebooks using Conda. This includes ipywidgets, ipyvolume, bqplot, and scipy.

```shell
conda install -c conda-forge ipywidgets ipyvolume bqplot scipy
```

--------------------------------

### Setup Development Environment

Source: https://voila.readthedocs.io/en/stable/_sources/contribute.md

Steps to set up a local development environment for Voilà. This includes creating a conda environment, cloning the repository, installing JavaScript dependencies, and installing Voilà in editable mode.

```bash
# create a new conda environment
conda create -n voila -c conda-forge notebook jupyterlab nodejs "yarn<4" pip
conda activate voila

# download voila from your GitHub fork
git clone https://github.com/<your-github-username>/voila.git

# install JS dependencies and build js assets
cd voila
yarn install

# install Voilà in editable mode
python -m pip install -e .
```

--------------------------------

### Install and Manage Nginx

Source: https://voila.readthedocs.io/en/stable/_sources/deploy.md

Installs the Nginx web server and checks its status. It also covers enabling and starting the Nginx service to ensure it runs automatically on boot.

```text
sudo apt install nginx
sudo systemctl status nginx
sudo systemctl enable nginx.service
sudo systemctl start nginx.service
```

--------------------------------

### Create Conda Environment for Examples

Source: https://voila.readthedocs.io/en/stable/_sources/using.md

Create a new conda environment to install dependencies for running Voilà's example notebooks. This is an alternative to installing directly into an existing environment.

```bash
conda env create
```

--------------------------------

### Setup JupyterLab Extension Development

Source: https://voila.readthedocs.io/en/stable/_sources/contribute.md

Instructions for setting up a development environment for the JupyterLab extension. This involves installing the package in development mode, linking it with JupyterLab, and building or watching for changes.

```bash
# install the package in development mode
python -m pip install -e .

# link your development version of the extension with JupyterLab
jupyter labextension develop . --overwrite

# build the lab extension
jlpm run build --scope @voila-dashboards/jupyterlab-preview

# start in watch mode to pick up changes automatically
jlpm run watch
```

--------------------------------

### Serve Example Notebook

Source: https://voila.readthedocs.io/en/stable/using

This example shows how to clone the Voilà repository, navigate into its directory, and then run a specific example notebook (`bqplot.ipynb`) using the Voilà command-line interface. This process renders the notebook as a standalone web application.

```shell
git clone https://github.com/voila-dashboards/voila
cd voila
voila notebooks/bqplot.ipynb
```

--------------------------------

### Example: Serve media files

Source: https://voila.readthedocs.io/en/stable/_sources/customize.md

A command-line example for serving common media file types (images, videos) while explicitly excluding notebook files.

```bash
voila mydir --VoilaConfiguration.file_allowlist="['.*\.(png|jpg|gif|svg|mp4|avi|ogg)']"
```

--------------------------------

### Setup Voilà JupyterLab Extension

Source: https://voila.readthedocs.io/en/stable/contribute

Steps to set up the Voilà JupyterLab extension for development. This involves installing Node.js, enabling the server extension, linking the development version, and building the extension, with an option to run in watch mode.

```shell
conda install -c conda-forge nodejs

jupyter serverextension enable voila --sys-prefix

jupyter serverextension list

python -m pip install -e .
jupyter labextension develop . --overwrite
jlpm run build --scope @voila-dashboards/jupyterlab-preview

# Optional: start in watch mode
jlpm run watch
```

--------------------------------

### Serve Example Notebook with Voilà

Source: https://voila.readthedocs.io/en/stable/_sources/using.md

Clone the Voilà repository, navigate to its directory, and run Voilà to serve the example notebooks. This demonstrates a common use case for testing and demonstration.

```bash
git clone https://github.com/voila-dashboards/voila
cd voila
voila notebooks/bqplot.ipynb
```

--------------------------------

### Setup Voilà Development Environment

Source: https://voila.readthedocs.io/en/stable/contribute

Steps to set up a local development environment for Voilà using Conda for environment management, Yarn for JavaScript dependencies, and Pip for Python package installation. This includes cloning the repository and installing Voilà in editable mode.

```shell
conda create -n voila -c conda-forge notebook jupyterlab nodejs "yarn<4" pip
conda activate voila

git clone https://github.com/<your-github-username>/voila.git

cd voila
yarn install

python -m pip install -e .
```

--------------------------------

### Basic Server Setup and Nginx Configuration

Source: https://voila.readthedocs.io/en/stable/deploy

Steps to install Nginx, check its status, and configure it as a reverse proxy for a Voilà application. This includes setting up the server block with proxy pass directives and necessary headers.

```shell
ssh ubuntu@<ip-address>
```

```shell
sudo apt install nginx
```

```shell
sudo systemctl status nginx
```

```shell
sudo systemctl enable nginx.service
sudo systemctl start nginx.service
```

--------------------------------

### Install Project Dependencies

Source: https://voila.readthedocs.io/en/stable/_sources/deploy.md

Installs all Python dependencies listed in the requirements.txt file using pip. This ensures the project has all necessary libraries to run.

```text
sudo python3 -m pip install -r requirements.txt
```

--------------------------------

### Start Voilà Locally

Source: https://voila.readthedocs.io/en/stable/_sources/deploy.md

Starts a local instance of Voilà serving a specified notebook without opening a browser. This command is used to prepare the application for sharing.

```shell
voila --no-browser my_notebook.ipynb
```

--------------------------------

### Manage Voilà Systemd Service

Source: https://voila.readthedocs.io/en/stable/_sources/deploy.md

Enables the Voilà systemd service to start on boot and starts the service immediately. This ensures Voilà is running and accessible.

```text
sudo systemctl enable voila.service
sudo systemctl start voila.service
```

--------------------------------

### Example: Serve all files except notebooks

Source: https://voila.readthedocs.io/en/stable/_sources/customize.md

A command-line example demonstrating how to configure Voilà to serve all files in a directory, excluding notebook files (`.ipynb`).

```bash
voila mydir --VoilaConfiguration.file_allowlist="['.*']" \
  --VoilaConfiguration.file_denylist="['.*\.ipynb']"
```

--------------------------------

### Example: Map Python and Julia scripts

Source: https://voila.readthedocs.io/en/stable/_sources/customize.md

A command-line example showing how to map `.py` files to the 'python' kernel and `.jl` files to the 'julia' kernel.

```bash
voila mydir --VoilaConfiguration.extension_language_mapping='{".py": "python", ".jl": "julia"}'
```

--------------------------------

### Example: Configure kernel culling as server extension

Source: https://voila.readthedocs.io/en/stable/_sources/customize.md

A command-line example showing how to configure kernel culling when using Voilà as a Jupyter server extension.

```bash
jupyter notebook --MappingKernelManager.cull_interval=60 --MappingKernelManager.cull_idle_timeout=120
```

--------------------------------

### Start Voilà Locally

Source: https://voila.readthedocs.io/en/stable/deploy

Starts a local instance of Voilà without opening a web browser. This command is a prerequisite for sharing the application via ngrok.

```bash
voila --no-browser my_notebook.ipynb
```

--------------------------------

### Run Voilà Application

Source: https://voila.readthedocs.io/en/stable/contribute

Instructions on how to start the Voilà application from the command line, either directly or as a Python module. This typically opens a browser tab at http://localhost:8866/.

```shell
voila
```

```shell
python -m voila
```

--------------------------------

### Install Python Pip

Source: https://voila.readthedocs.io/en/stable/_sources/deploy.md

Installs pip, the package installer for Python, which is necessary for managing Python project dependencies.

```text
sudo apt update && sudo apt install python3-pip
```

--------------------------------

### Install Voila Test Dependencies

Source: https://voila.readthedocs.io/en/stable/_sources/contribute.md

Installs the necessary Python packages for testing Voila, including development dependencies. This command ensures all required libraries are available in the current environment.

```bash
python -m pip install -e ".[test]"
```

--------------------------------

### Run Voilà

Source: https://voila.readthedocs.io/en/stable/_sources/contribute.md

Commands to start the Voilà application. This will typically open a new browser tab at http://localhost:8866/.

```bash
voila
```

```bash
python -m voila
```

--------------------------------

### Install Test Dependencies

Source: https://voila.readthedocs.io/en/stable/contribute

Installs the project in editable mode with test dependencies included. This command is crucial for setting up a local development environment for running tests.

```shell
python -m pip install -e ".[test]"
```

--------------------------------

### Voilà Instantiation Command for Apache Proxy

Source: https://voila.readthedocs.io/en/stable/deploy

The command used to start a Voilà instance when using Apache2 as a reverse proxy, specifying the port and base URL for the application.

```shell
$ voila --autoreload=True --port=50001 --base_url=/voila/
```

--------------------------------

### Copy Base Template Files for Customization

Source: https://voila.readthedocs.io/en/stable/_sources/customize.md

Copies the default nbconvert and HTML template files from an existing Voilà installation to the new custom template directory. This provides a starting point for modifications.

```bash
cp -r path/to/env/share/jupyter/voila/templates/default/nbconvert_templates ./
cp -r path/to/env/share/jupyter/voila/templates/default/templates ./
```

--------------------------------

### Install Voilà with Pip

Source: https://voila.readthedocs.io/en/stable/_sources/install.md

Installs Voilà using the pip package manager from the Python Package Index (PyPI). This is a standard method for installing Python packages.

```bash
pip install voila
```

--------------------------------

### Create Conda Environment

Source: https://voila.readthedocs.io/en/stable/using

Creates a new Conda environment, likely to set up dependencies for running the example notebooks.

```shell
conda env create
```

--------------------------------

### Example: Map Python scripts to xeus-python kernel

Source: https://voila.readthedocs.io/en/stable/_sources/customize.md

A command-line example that maps `.py` files to the 'python' language and specifies the 'xpython' kernel for executing Python scripts.

```bash
voila mydir --VoilaConfiguration.extension_language_mapping='{".py": "python", ".jl": "julia"}' \
  --VoilaConfiguration.language_kernel_mapping='{"python": "xpython"}'
```

--------------------------------

### Access Voilà as Jupyter Server Extension

Source: https://voila.readthedocs.io/en/stable/using

This shows the URL pattern to access Voilà when it's installed as a Jupyter server extension. After starting a Jupyter server (like `jupyter lab` or `jupyter notebook`), appending `/voila` to the server's URL will activate Voilà, serving the directory where the Jupyter server was initiated.

```url
<url-of-my-server>/voila
```

--------------------------------

### Managing Voilà Service with Systemd

Source: https://voila.readthedocs.io/en/stable/deploy

Commands to enable and start the Voilà systemd service, ensuring it runs automatically on boot and is managed by the system's service manager.

```shell
sudo systemctl enable voila.service
sudo systemctl start voila.service
```

```shell
journalctl -u voila.service
```

--------------------------------

### Enable Kernel Preheating and Set Pool Size (Voilà CLI)

Source: https://voila.readthedocs.io/en/stable/customize

Activates the kernel preheating feature in Voilà, which starts a pool of kernels in advance to reduce waiting times. `pool_size` specifies the number of kernels to maintain in the standby pool for each notebook. This feature is incompatible with `prelaunch-hook`.

```shell
voila --preheat_kernel=True --pool_size=5
```

--------------------------------

### Install Voila Template Test Dependencies

Source: https://voila.readthedocs.io/en/stable/_sources/contribute.md

Installs specific test template packages required for running Voila tests locally. These templates are used to test Voila's template rendering capabilities.

```bash
python -m pip install ./tests/test_template ./tests/skip_template
```

--------------------------------

### Install Test Template Packages

Source: https://voila.readthedocs.io/en/stable/contribute

Installs specific test template packages required for running Voila's local tests. These packages provide necessary fixtures or data for the testing suite.

```shell
python -m pip install ./tests/test_template ./tests/skip_template
```

--------------------------------

### Launching Voilà Programmatically with Custom Hooks

Source: https://voila.readthedocs.io/en/stable/_sources/customize.md

Demonstrates how to programmatically configure and launch a Voilà application with custom prelaunch and page configuration hooks. This involves creating a `VoilaConfiguration` object, assigning hooks, and starting the Voilà app.

```python
from voila.app import Voila
from voila.config import VoilaConfiguration

# customize config how you like
config = VoilaConfiguration()

# set the prelaunch hook
config.prelaunch_hook = parameterize_with_papermill

# set the page config hook
config.page_config_hook = page_config_hook

# create a voila instance
app = Voila()

# set the config
app.voila_configuration = config

# launch
app.start()

```

--------------------------------

### Start ngrok Tunnel

Source: https://voila.readthedocs.io/en/stable/deploy

Starts an ngrok tunnel to expose a local server running on a specific port (defaulting to 8866 for Voilà) to the public internet. This command is essential for making the local Voilà application accessible externally.

```bash
ngrok http 8866
```

--------------------------------

### Install and Enable Voilà Notebook Extension

Source: https://voila.readthedocs.io/en/stable/contribute

Commands to install and enable the Voilà extension for the classic Jupyter Notebook interface. This ensures Voilà functionality is available within the notebook environment.

```shell
jupyter nbextension install voila --sys-prefix --py
jupyter nbextension enable voila --sys-prefix --py
```

--------------------------------

### Voila Command Line for Apache Proxy

Source: https://voila.readthedocs.io/en/stable/_sources/deploy.md

The command used to start Voilà when configured with Apache2 as a reverse proxy. It specifies the port and base URL for the Voilà instance.

```text
$ voila --autoreload=True --port=50001 --base_url=/voila/
```

--------------------------------

### Voila Command-Line Options

Source: https://voila.readthedocs.io/en/stable/customize

Examples of using Voila command-line arguments to enable kernel preheating with custom environment variables and to hide notebook cells based on tags.

```shell
voila --preheat_kernel=True --VoilaKernelManager.default_env_variables='{"VOILA_WS_PROTOCOL":"wss","VOILA_APP_IP":"192.168.1.1"}'
```

```shell
voila --TagRemovePreprocessor.remove_all_outputs_tags='{"hide"}' your_notebook.ipynb
```

```shell
voila --TagRemovePreprocessor.remove_cell_tags='{"hide"}' your_notebook.ipynb
```

--------------------------------

### Build and Lint Frontend Packages

Source: https://voila.readthedocs.io/en/stable/_sources/contribute.md

Commands to manage frontend packages within the Voilà monorepo. This includes installing dependencies, building all packages, and running linters like ESLint and Prettier to maintain code quality and style.

```bash
# install dependencies
jlpm

# build the packages
jlpm run build
```

```bash
# install dependencies
jlpm

# run ESLint
jlpm run eslint

# run prettier
jlpm run prettier
```

--------------------------------

### Start ngrok Tunnel

Source: https://voila.readthedocs.io/en/stable/_sources/deploy.md

Starts an ngrok tunnel to expose local services running on a specific port (e.g., 8866) to the public internet. This command generates a public URL to access the local Voilà application.

```shell
ngrok http 8866
```

--------------------------------

### Manage Voilà Extensions

Source: https://voila.readthedocs.io/en/stable/_sources/contribute.md

Commands for enabling and installing Voilà extensions for different Jupyter environments (classic notebook, Jupyter Server, and JupyterLab).

```bash
# Manually enable the classic notebook server extension
jupyter serverextension enable voila --sys-prefix
```

```bash
# Enable for Jupyter Server
jupyter server extension enable voila.server_extension --sys-prefix
```

```bash
# Install the notebook extension
jupyter nbextension install voila --sys-prefix --py
jupyter nbextension enable voila --sys-prefix --py
```

```bash
# Enable JupyterLab server extension (requires Node.js)
conda install -c conda-forge nodejs
jupyter serverextension enable voila --sys-prefix
```

```bash
# Verify server extension status
jupyter serverextension list
```

--------------------------------

### Lint and Format Voila Packages

Source: https://voila.readthedocs.io/en/stable/contribute

Installs project dependencies and then runs ESLint for code linting and Prettier for code formatting. These commands ensure code quality and consistency across the project.

```shell
jlpm
jlpm run eslint
jlpm run prettier
```

--------------------------------

### Systemd Service Configuration for Voilà

Source: https://voila.readthedocs.io/en/stable/deploy

A systemd service unit file to manage the Voilà application. It defines how to start, stop, and restart the Voilà process, specifying the user, working directory, and restart policy.

```systemd
[Unit]
Description=Voila

[Service]
Type=simple
PIDFile=/run/voila.pid
ExecStart=voila --no-browser voila/notebooks/basics.ipynb
User=ubuntu
WorkingDirectory=/home/ubuntu/
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Start Voila with Personalized Token

Source: https://voila.readthedocs.io/en/stable/changelog

This command starts Voila with a user-defined, personalized token for authentication. This method allows for specific security token management when running Voila.

```shell
voila --token=my-secret-token notebook.ipynb
```

--------------------------------

### Start Voila with Auto-Generated Token

Source: https://voila.readthedocs.io/en/stable/changelog

This command starts Voila using the token-based authentication system, automatically generating a token for secure access. It requires the 'jupyter-server' 2 backend.

```shell
voila --token notebook.ipynb
```

--------------------------------

### Use a specific Voilà template (e.g., gridstack)

Source: https://voila.readthedocs.io/en/stable/customize

An example command demonstrating how to activate a specific template, such as the 'gridstack' template, which provides a drag-and-drop cell layout.

```shell
voila <path-to-notebook> --template=gridstack
```

--------------------------------

### Voilà Configuration File Hooks

Source: https://voila.readthedocs.io/en/stable/_sources/customize.md

Defines prelaunch and page configuration hook functions within a `voila.py` file. These functions allow customization of notebook execution and page rendering before Voilà starts.

```python
def prelaunch_hook_function(req, notebook, cwd):
   """Do your stuffs here"""
   return notebook

def page_config_hook_function(current_page_config, **kwargs):
   """Modify the current_page_config"""
   return new_page_config

c.VoilaConfiguration.prelaunch_hook = hook_function
c.VoilaConfiguration.page_config_hook = page_config_hook

```

--------------------------------

### Enabling HTTPS with Certbot and Nginx

Source: https://voila.readthedocs.io/en/stable/deploy

Steps to install Certbot and its Nginx plugin, obtain SSL certificates from Let's Encrypt, and automatically update the Nginx configuration for HTTPS. Includes commands for certificate renewal.

```shell
sudo add-apt-repository ppa:certbot/certbot
sudo apt update
sudo apt install python-certbot-nginx
```

```shell
sudo certbot --nginx -d yourdomain.com
```

```shell
crontab -e
```

```shell
0 12 * * * /usr/bin/certbot renew --quiet
```

--------------------------------

### Custom Voilà Template Directory Structure Example

Source: https://voila.readthedocs.io/en/stable/customize

Shows the directory structure after copying default template files into a custom template folder.

```shell
tree .
├── nbconvert_templates
│   ├── base.tpl
│   └── voila.tpl
└── templates
    ├── 404.html
    ├── error.html
    ├── page.html
    └── tree.html
```

--------------------------------

### Voila Systemd Service Configuration

Source: https://voila.readthedocs.io/en/stable/_sources/deploy.md

Defines a systemd service unit for Voilà. This configuration ensures Voilà starts automatically on boot, restarts if it crashes, and runs as a specific user with a defined working directory and command.

```APIDOC
[Unit]
Description=Voila

[Service]
Type=simple
PIDFile=/run/voila.pid
ExecStart=voila --no-browser voila/notebooks/basics.ipynb
User=ubuntu
WorkingDirectory=/home/ubuntu/
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Enable HTTPS with Certbot

Source: https://voila.readthedocs.io/en/stable/_sources/deploy.md

Installs Certbot and its Nginx plugin, then obtains SSL/TLS certificates from Let's Encrypt for a specified domain. Certbot automatically updates the Nginx configuration to use the new certificates.

```text
sudo add-apt-repository ppa:certbot/certbot
sudo apt update
sudo apt install python-certbot-nginx
sudo certbot --nginx -d yourdomain.com
```

--------------------------------

### Build All Frontend Packages

Source: https://voila.readthedocs.io/en/stable/contribute

Command to install all project dependencies using Yarn (jlpm) and build all frontend packages within the monorepo structure. This is a comprehensive step for ensuring all frontend assets are correctly compiled.

```shell
jlpm

```

--------------------------------

### Voilà Token Authentication Activation

Source: https://voila.readthedocs.io/en/stable/customize

Shows how to activate token authentication for Voilà. It covers starting Voilà with an auto-generated token or a personalized secret token for secure access.

```bash
voila --token notebook.ipynb
```

```bash
voila --token=my-secret-token notebook.ipynb
```

--------------------------------

### Customize Notebook Execution with Papermill Hook

Source: https://voila.readthedocs.io/en/stable/customize

An example of a prelaunch hook function that uses Papermill to parameterize a notebook. It retrieves parameters from the request arguments and injects them into the notebook before execution.

```python
def parameterize_with_papermill(req, notebook, cwd):
    import tornado

    # Grab parameters
    parameters = req.get_argument("parameters", {})

    # try to convert to dict if not e.g. string/unicode
    if not isinstance(parameters, dict):
        try:
            parameters = tornado.escape.json_decode(parameters)
        except ValueError:
            parameters = None

    # if passed and a dict, use papermill to inject parameters
    if parameters and isinstance(parameters, dict):
        from papermill.parameterize import parameterize_notebook

        # setup for papermill
        #
        # these two blocks are done
        # to avoid triggering errors
        # in papermill's notebook
        # loading logic
        for cell in notebook.cells:
            if 'tags' not in cell.metadata:
                cell.metadata.tags = []
            if "papermill" not in notebook.metadata:
                notebook.metadata.papermill = {}

        # Parameterize with papermill
        return parameterize_notebook(notebook, parameters)

```

--------------------------------

### Apache2 Reverse Proxy Configuration for Voilà

Source: https://voila.readthedocs.io/en/stable/deploy

An example Apache VirtualHost configuration for serving Voilà applications, including proxying HTTP and WebSocket traffic. It requires specific Apache modules to be enabled.

```apache
<VirtualHost *:443>
   # ...
   ProxyRequests Off
   ProxyPreserveHost Off

   <LocationMatch  "/voila/">
      RewriteEngine on
      RewriteCond %{REQUEST_URI} /voila/api/kernels/
      RewriteRule .*/voila/(.*) "ws://127.0.0.1:50001/voila/$1" [P,L]
      ProxyPreserveHost On
      ProxyPass http://127.0.0.1:50001/voila/
      ProxyPassReverse  http://127.0.0.1:50001/voila/
   </LocationMatch>
</VirtualHost>
```

--------------------------------

### Voilà Configuration for Kernel Environment Variables

Source: https://voila.readthedocs.io/en/stable/_sources/customize.md

An example of a `voila.json` configuration file to set environment variables for a specific notebook's kernel pool. This is used to configure WebSocket protocol, IP address, and port.

```json
{
   "VoilaKernelManager": {
      "kernel_pools_config": {
         "foo.ipynb": {
            "kernel_env_variables": {
               "VOILA_APP_IP": "192.168.1.1",
               "VOILA_APP_PORT": "6789",
               "VOILA_WS_PROTOCOL": "wss"
            }
         }
      }
   }
}
```

--------------------------------

### Clone Voilà Repository

Source: https://voila.readthedocs.io/en/stable/deploy

Clones the Voilà repository and navigates into the notebooks directory to set up a project for deployment.

```bash
git clone git@github.com:voila-dashboards/voila.git
cd voila/notebooks/
```

--------------------------------

### Install Voilà with Pip

Source: https://voila.readthedocs.io/en/stable/install

Installs Voilà using the pip package installer from the Python Package Index (PyPI). This method is suitable for users who prefer pip for package management.

```shell
pip install voila
```

--------------------------------

### Clone Voilà Repository and Navigate

Source: https://voila.readthedocs.io/en/stable/_sources/deploy.md

Clones the Voilà Git repository and changes the directory to the notebooks folder, setting up the project root for deployment.

```bash
git clone git@github.com:voila-dashboards/voila.git
cd voila/notebooks/
```

--------------------------------

### Install Voilà with Mamba

Source: https://voila.readthedocs.io/en/stable/_sources/install.md

Installs Voilà using the mamba package manager from the conda-forge channel. Mamba is a fast, parallel drop-in replacement for conda.

```bash
mamba install -c conda-forge voila
```

--------------------------------

### Install Voilà with Mamba/Conda

Source: https://voila.readthedocs.io/en/stable/install

Installs Voilà using the mamba or conda package manager from the conda-forge channel. This is a common method for managing Python environments and packages.

```shell
mamba install -c conda-forge voila
```

--------------------------------

### Serve Directory of Jupyter Notebooks

Source: https://voila.readthedocs.io/en/stable/_sources/using.md

Navigate to a directory containing Jupyter notebooks and run the 'voila' command. Voilà will serve a page listing the notebooks, allowing users to click and render them.

```bash
cd notebooks/
voila
```

--------------------------------

### Railway: Git Initialization and Committing

Source: https://voila.readthedocs.io/en/stable/deploy

Commands to initialize a Git repository, stage all project files, and create an initial commit for deployment.

```shell
git init
git add <your-files>
git commit -m "my message"
```

--------------------------------

### Google App Engine: Entrypoint for Specific Notebook

Source: https://voila.readthedocs.io/en/stable/deploy

Modifies the entrypoint in `app.yaml` for Google App Engine to serve a single specified notebook instead of all available notebooks.

```yaml
entrypoint: voila --port=$PORT --Voila.ip=0.0.0.0 --no-browser your_notebook.ipynb
```

--------------------------------

### Example: Configure kernel culling

Source: https://voila.readthedocs.io/en/stable/_sources/customize.md

A command-line example to configure the Jupyter Server to cull idle kernels. It sets the check interval to 60 seconds and the idle timeout to 120 seconds.

```bash
voila --MappingKernelManager.cull_interval=60 --MappingKernelManager.cull_idle_timeout=120
```

--------------------------------

### Google App Engine: Deployment and Browse Commands

Source: https://voila.readthedocs.io/en/stable/deploy

Commands to deploy the application to Google App Engine and open the deployed application in a web browser. `gcloud app deploy` uploads the code, and `gcloud app browse` opens the service URL.

```shell
gcloud app deploy
gcloud app browse
```

--------------------------------

### Railway: CLI Deployment Commands

Source: https://voila.readthedocs.io/en/stable/deploy

Commands to initialize a Railway instance, deploy the code, and view application logs. `railway init` sets up the project, `railway up --detach` deploys in the background, and `railway up` shows logs.

```shell
railway init
railway up --detach
railway up
```

--------------------------------

### Voila Configuration (`voila.json`)

Source: https://voila.readthedocs.io/en/stable/customize

Defines Voila's operational parameters, including kernel preheating activation, denylist for preheating, and detailed configuration for kernel pools per notebook, with default settings.

```json
{
   "VoilaConfiguration": {
      "preheat_kernel": true
   },
   "VoilaKernelManager": {
      "preheat_denylist": [
         "notebook-does-not-need-preheat.ipynb",
         "^.*foo.*$"
      ],
      "kernel_pools_config": {
         "voila.ipynb": {
            "pool_size": 3,
            "kernel_env_variables": {
               "foo2": "bar2"
            }
         },
         "test/sub-voila.ipynb": {
            "pool_size": 1
         },
         "default": {
            "pool_size": 2,
            "kernel_env_variables": {
               "foo": "bar"
            }
         }
      },
      "fill_delay": 0
   }
}
```

--------------------------------

### Google App Engine: Flexible Environment Configuration

Source: https://voila.readthedocs.io/en/stable/deploy

Defines the runtime and entrypoint for a Google App Engine flexible environment deployment. It specifies Python 3 and the Voilà command to run.

```yaml
runtime: python
env: flex
runtime_config:
  python_version: 3
entrypoint: voila --port=$PORT --Voila.ip=0.0.0.0 --no-browser
```

--------------------------------

### Command-line Configuration for Kernel Environment Variables

Source: https://voila.readthedocs.io/en/stable/_sources/customize.md

Illustrates how to set environment variables for Voilà's kernel using command-line arguments. This allows for runtime configuration of WebSocket protocol and IP address.

```bash
voila --preheat_kernel=True --VoilaKernelManager.default_env_variables='{"VOILA_WS_PROTOCOL":"wss","VOILA_APP_IP":"192.168.1.1"}'
```

--------------------------------

### Serve Directory of Notebooks

Source: https://voila.readthedocs.io/en/stable/using

This command illustrates how to serve all Jupyter notebooks within a specific directory using Voilà. By navigating to the target directory and running `voila`, the tool will present a list of notebooks, allowing users to click and render them individually. Each rendered notebook spawns a new Jupyter kernel.

```shell
cd notebooks/
voila
```

--------------------------------

### Project Dependencies

Source: https://voila.readthedocs.io/en/stable/deploy

Lists Python dependencies required for the Voilà application to run. This file is essential for deployment environments.

```text
bqplot
ipympl
ipyvolume
scipy
voila
```

--------------------------------

### Customize Voilà Theme and Template on Binder

Source: https://voila.readthedocs.io/en/stable/_sources/deploy.md

Specifies Voilà configuration options like theme and template by creating a jupyter_config.json file.

```json
{
  "VoilaConfiguration": {
    "theme": "dark",
    "template": "gridstack"
  }
}
```

--------------------------------

### Activating Token Authentication in Voilà

Source: https://voila.readthedocs.io/en/stable/_sources/customize.md

Details how to enable token authentication for Voilà, leveraging `jupyter-server` 2. This can be done by starting Voilà with an auto-generated token or a personalized secret token.

```shell
voila --token notebook.ipynb

voila --token=my-secret-token notebook.ipynb

```

--------------------------------

### Voilà template directory locations

Source: https://voila.readthedocs.io/en/stable/customize

Voilà searches for custom templates in several standard Jupyter configuration directories. These locations are crucial for Voilà to discover and load user-defined or installed templates.

```shell
~/.local/share/jupyter/voila/templates
~/path/to/env/dev/share/jupyter/voila/templates
/usr/local/share/jupyter/voila/templates
/usr/share/jupyter/voila/templates
```

--------------------------------

### Railway: Procfile for All Notebooks

Source: https://voila.readthedocs.io/en/stable/deploy

Configures the web process for Railway to run Voilà, serving all notebooks in the project. It sets the port, disables browser launch, and binds to all interfaces.

```shell
web: voila --port=$PORT --no-browser --Voila.ip=0.0.0.0
```

--------------------------------

### Use Custom JupyterLab Themes

Source: https://voila.readthedocs.io/en/stable/_sources/customize.md

Enables the use of custom JupyterLab themes by installing the theme package and specifying its name. Note that custom themes are only compatible with the default tree page.

```bash
pip install jupyterlab_miami_nights
voila <path-to-notebook> --theme="JupyterLab Miami Nights"
```

--------------------------------

### Get Query String in Python

Source: https://voila.readthedocs.io/en/stable/_sources/customize.md

Demonstrates how to access the URL query string within a Python script running in a Voilà notebook. This is useful for dynamically rendering widgets with user-specific data.

```python
import os
query_string = os.getenv('QUERY_STRING')
```

--------------------------------

### Run Voilà as Standalone Application

Source: https://voila.readthedocs.io/en/stable/_sources/using.md

Use Voilà from the command line to run, convert, and serve a Jupyter notebook as a standalone app. It specifies the notebook path and optional arguments.

```bash
voila <path-to-notebook> <options>
```

--------------------------------

### Customize Frontend URL with Page Config Hook

Source: https://voila.readthedocs.io/en/stable/customize

An example of a page_config hook function that modifies the `fullLabextensionsUrl` setting. This allows users to specify custom URLs for frontend assets like labextensions.

```python
def page_config_hook(
   current_page_config: Dict[str, Any],
   base_url: str,
   settings: Dict[str, Any],
   log: Logger,
   voila_configuration: VoilaConfiguration,
   notebook_path: str
):
    page_config['fullLabextensionsUrl'] = '/custom/labextensions_url'
    return page_config

```

--------------------------------

### Certbot Managed Nginx SSL Configuration

Source: https://voila.readthedocs.io/en/stable/_sources/deploy.md

Example snippet showing how Certbot modifies the Nginx configuration to enable SSL/TLS on port 443, including paths to certificate files and SSL options.

```nginx
listen 443 ssl;
ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.key;
include /etc/letsencrypt/options-ssl-nginx.conf;
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
```

--------------------------------

### Voilà Project Dependencies

Source: https://voila.readthedocs.io/en/stable/_sources/deploy.md

Lists Python dependencies required for a Voilà application, typically placed in a requirements.txt file.

```text
bqplot
ipympl
ipyvolume
scipy
voila
```

--------------------------------

### Railway: Procfile for Specific Notebook

Source: https://voila.readthedocs.io/en/stable/deploy

Configures the web process for Railway to run Voilà, serving a single specified notebook. It sets the port, disables browser launch, and binds to all interfaces.

```shell
web: voila --port=$PORT --no-browser --Voila.ip=0.0.0.0 your_notebook.ipynb
```

--------------------------------

### Activate Classic Tree Page

Source: https://voila.readthedocs.io/en/stable/_sources/customize.md

Enables the jinja-based tree page instead of the default JupyterLab-based one. This can be done via CLI option or configuration.

```bash
voila <path-to-notebook> --classic-tree
```

--------------------------------

### Create and Navigate to Custom Template Directory

Source: https://voila.readthedocs.io/en/stable/_sources/customize.md

Commands to create a new directory for a custom Voilà template and navigate into it. This is the first step in building a new template from scratch.

```bash
mkdir ~/.local/share/jupyter/voila/templates/mytemplate
cd ~/.local/share/jupyter/voila/templates/mytemplate
```

--------------------------------

### Configure Voilà Preview Widget Position in JupyterLab

Source: https://voila.readthedocs.io/en/stable/customize

Uses JupyterLab's layout customization system to change the default area of the Voilà Preview widget. This example places the widget in the right panel of the JupyterLab interface.

```json
{
   "layout": {
      "multiple": {
         "Voila Preview": { "area": "right" }
      }
   }
}
```

--------------------------------

### Switch to Classic Tree Page

Source: https://voila.readthedocs.io/en/stable/customize

Activates the legacy jinja-based tree page instead of the default JupyterLab-based file browser. This can be done via CLI option, configuration setting, or a query parameter in the URL.

```bash
voila <path-to-notebook> --classic-tree
```

--------------------------------

### Access Voilà as Jupyter Server Extension

Source: https://voila.readthedocs.io/en/stable/_sources/using.md

After starting a Jupyter server (e.g., 'jupyter lab'), access Voilà by navigating to the '/voila' endpoint appended to the server's URL. This integrates Voilà into an existing Jupyter environment.

```bash
<url-of-my-server>/voila
```

--------------------------------

### Map Script Extensions to Kernels

Source: https://voila.readthedocs.io/en/stable/_sources/customize.md

Configure how Voilà maps file extensions to specific kernel languages and how to specify which kernel to use for a given language. This enables running script files as notebooks.

```APIDOC
VoilaConfiguration.extension_language_mapping
  Description: A dictionary mapping file extensions (e.g., '.py') to language names (e.g., 'python').
  Example: '{".py": "python", ".jl": "julia"}'

VoilaConfiguration.language_kernel_mapping
  Description: A dictionary mapping language names (e.g., 'python') to specific kernel names (e.g., 'xpython').
  Example: '{"python": "xpython"}'
  Note: This allows specifying kernels like xeus-python.
```

--------------------------------

### Linking Custom Static Files in Voilà Templates

Source: https://voila.readthedocs.io/en/stable/customize

Demonstrates how to link custom static files (like CSS or JavaScript) within Voilà templates. It shows the base URL structure and provides an example for linking a CSS file.

```html
<link rel="stylesheet" type="text/css" href="{{resources.base_url}}voila/static/css/custom.css"></link>
```

--------------------------------

### Voilà Kernel Preheating Configuration

Source: https://voila.readthedocs.io/en/stable/_sources/customize.md

Defines comprehensive settings for Voilà's preheated kernel functionality using a JSON configuration file. This includes activating the feature, specifying denylisted notebooks, configuring kernel pool sizes and environment variables per notebook, and setting the pool refilling delay.

```APIDOC
{
   "VoilaConfiguration": {
      "preheat_kernel": true
   },
   "VoilaKernelManager": {
      "preheat_denylist": [
         "notebook-does-not-need-preheat.ipynb",
         "^.*foo.*$"
      ],
      "kernel_pools_config": {
         "voila.ipynb": {
            "pool_size": 3,
            "kernel_env_variables": {
               "foo2": "bar2"
            }
         },
         "test/sub-voila.ipynb": {
            "pool_size": 1
         },
         "default": {
            "pool_size": 2,
            "kernel_env_variables": {
               "foo": "bar"
            }
         }
      },
      "fill_delay": 0
   }
}
```

--------------------------------

### Customize Voilà Preview Widget Layout

Source: https://voila.readthedocs.io/en/stable/_sources/customize.md

Example JavaScript configuration for JupyterLab's layout system to change the default placement of the Voilà preview widget. This allows users to open the widget in different panels, such as the right sidebar.

```javascript
"layout": {
   "multiple": {
      "Voila Preview": { "area": "right" }
   }
}
```

--------------------------------

### Google Cloud CLI Deployment Commands

Source: https://voila.readthedocs.io/en/stable/_sources/deploy.md

Shell commands to deploy a Voilà application to Google App Engine and browse the deployed application.

```bash
gcloud app deploy
```

```bash
gcloud app browse
```

--------------------------------

### Launch Voila with Custom Hooks via Python Script

Source: https://voila.readthedocs.io/en/stable/customize

Shows how to launch a Voila application programmatically from a Python script, setting custom prelaunch and page_config hooks. This involves creating a VoilaConfiguration object, assigning the hook functions, and starting the Voila app.

```python
from voila.app import Voila
from voila.config import VoilaConfiguration

# customize config how you like
config = VoilaConfiguration()

# set the prelaunch hook
config.prelaunch_hook = parameterize_with_papermill

# set the page config hook
config.page_config_hook = page_config_hook

# create a voila instance
app = Voila()

# set the config
app.voila_configuration = config

# launch
app.start()

```
Tokens:
Raw