Access Multiple Hosted Applications in one Workspace Session

For security reasons, Domino Workspace sessions are only accessible on one port. For example, Jupyter typically uses port 8888. When you launch a Jupyter Workspace session, a Domino executor starts the Jupyter server in a Run, and opens port 8888 to serve the Jupyter application to your browser. If you were to try to use the Jupyter terminal to start another application on a different port, it would not be accessible.

However, in some cases you might want to run multiple interactive applications in the same Workspace session. These cases include:

Editing and debugging Dash or Flask apps live
Using Tensorboard to view progress of a live training job

Domino 3.5+ supports this with Jupyter Server Proxy and JupyterLab.

Prerequisites

Python 3+
Jupyter Server Proxy

Jupyter Server Proxy is installed by default in the latest Domino Standard Environments. To install it in one of your existing environments, see the following instructions.

Install Jupyter Server Proxy in your environment

If you are not on the recent version of the Domino Standard Environment, you can use the following steps to install Jupyter Server Proxy in your Domino Environment.

Add the following lines to your environment’s Dockerfile Instructions.

USER root

# Install NodeJS
# You can omit this step if your environment already has NodeJS installed
RUN curl -sL https://deb.nodesource.com/setup_16.x | bash - && \
   apt-get install nodejs -y && \
   rm -rf /var/lib/apt/lists/*

# Install jupyterlab-server-proxy (omit if already installed)
RUN if [ -x /opt/conda/bin/conda ]; then \
      /opt/conda/bin/conda install -y -c conda-forge jupyter-server-proxy; \
   else \
      pip install --no-cache-dir jupyter-server-proxy; \
   fi

# Update jupyter lab config
RUN mkdir -p home/ubuntu/.jupyterlab/ && \
   echo "c.ServerProxy.servers = {" >> home/ubuntu/.jupyterlab/jupyter_lab_config.py && \
   echo "    'code': {" >> home/ubuntu/.jupyterlab/jupyter_lab_config.py && \
   # Vscode example. Replace this command with what you want to proxy to
   echo "        'command': ['code-server', '--port', '{port}', '--auth', 'none']" >> /home/ubuntu/.jupyterlab/jupyter_lab_config.py && \
   echo "    }" >> /home/ubuntu/.jupyterlab/jupyter_lab_config.py && \
   echo "}" >> /home/ubuntu/.jupyterlab/jupyter_lab_config.py

USER ubuntu

Use Jupyter Server Proxy

If you launch a JupyterLab Workspace session in an environment with Jupyter Server Proxy installed, you can start and serve additional applications if they are served on a different port than JupyterLab.

By defining a new entry in the JupyterLab config (as done in the previous section), you can add a new tile to your JupyterLab launcher page.

Example

Add the following to your JupyterLab config in /home/ubuntu/.jupyterlab/jupyter_lab_config.py.

c.ServerProxy.servers = {
   'VSCode': {
      'command': ['code-server', '--port', '{port}']
   }
}

Use {port} for the port from which you want to serve this new application. After updating the JupyterLab config you will see a new tile under Notebook when you run start your workspace.

Click this new tile to open a new window that runs the specified command. With this model you can host multiple applications on different ports and expose each through your JupyterLab workspace.

If you edit the source files in JupyterLab after the application is running, you must restart the app in the browser for the edits will take effect.

For environments that have VSCode installed in JupyterLab, you can start a VSCode session from JupyterLab, and then start an App from VSCode. This allows you to debug using VSCode.

A new App or process that you start and open in a separate tab will not have the Domino Workspace with options to stop, sync, commit, or manage your project files. To access this application and manage your changes, you must open the main JupyterLab tab for your Workspace session.