Voilà allows you to convert a Jupyter Notebook into an interactive dashboard that allows you to share your work with others. It is secure and customizable, giving you control over what your readers experience.

Under ARE, the Voilà App allows you to start a Voilà instance dedicated for your use.

At this stage, you need to join project dk92 or up99 to access Voilà Apps under ARE.

Starting a Voilà session with a target Jupyter notebook


Note

Replace "YOUR_PROEJCT" below with your own NCI project id.

There are several pre-built environments you can use to run Voilà  Apps, such as NCI-data-analyisis/2024.05 under project dk92, or NCI-geophys/24.08 under project up99. You can also use your own environment with Voila 0.5.0 or higher installed. The environment should contains some basic packages like jupyterlab, ipywidgets etc. in addition to voila. For more detail on how to install Voila, please refer to https://voila.readthedocs.io/en/stable/install.html

Some example notebooks are available under "/g/data/dk92/notebooks/examples-voila".


You can start a session to render an existing Jupyter notebook directly as below:

  1. Login to ARE: https://are.nci.org.au/
  2. Click the Voilà icon on the Dashboard (home page)

3. Choose:

    1. the target Path to the notebook you want to open directly. 
    2. the number of hours you want your session to run for (maximum).
    3. the compute queue you want to submit the job to.
    4. the size of the compute resources you have access to (maximum).  If you attempt to exceed the CPU limit your processes will be throttled to the amount requested.  If you exceed the memory, your Jupyter Kernel may be terminated. Note: this is the resources used within the notebook; if you offload the processing to other jobs (e.g. using Dask) then you may not need a very large JupyterLab session.
    5. select which project to allocate the SU from (must be a project with a current allocation, or the session will not start). 
    6. select what storage (gdata and scratch areas) are required for your job to run.
    7. select additional software licenses if required for your job.
    8. Module directories: a space-separated list of additional directories to search for modulefile definitions. If these are under /g/data or /scratch, make sure you've included the appropriate directive(s) in your storage options above.
    9. Modules: a space-separated list of modules to be loaded.
    10. Python or Conda virtual environment base: specify the top-level directory of a custom virtual env, or the base directory of a conda environment. If this is under /g/data or /scratch, make sure you have included the appropriate directive in your storage options above.
    11. Conda environment: specify the name of a conda environment to activate. You must supply a conda base directory in order for this to work.
    12. if you want to receive an email once your session has started, check the box before "I would like to receive an email when the session starts". This is useful when the cluster is busy and your session is queued waiting for a free slot.

4. Additional settings needed for your job in "Advanced Options..."

    1. Extra arguments provided to the Voilà command line.
    2. Environment variables to be defined.
    3. jobfs size allocated to your job.
    4. Additional PBS flags not covered by other options.
    5. A pre-script to be run in your job before JupyterLab starts.


5.  Click "Launch" button to start a Voila session.

6. Initially it will show the status as Queued until your session begins to start. 

Once it is finished it will change to Running and look like the figure below:

7. Click the Open Voila button

8. This will open a new tab in your web browser that shows your rendered Jupyter notebook. It will execute all notebook cells.

The rendered Notebook will now displayed in the web browser:

9. If you close this window, your Voilà session will continue running. To end your session, you can either Shutdown (last item in File menu) or delete the job on the Interactive Sessions page of ARE.


Starting a Voilà session to explore multiple Jupyter notebooks

Just put "/" in the target Path to notebook field and keep all other options the same with above.

After clicking the Open Voila button in Step #8, you will enter the file explorer from the root directory "/". 

Navigate to your target notebook and click it to open.

You will be brought to your rendered dashboard.

You can use the file explorer to open another notebook and view its converted dashboard in a new tab of your web browser. 





  • No labels