jupyter-forward

• jupyter-forward
  • Badges
  • Overview
  • Usage
    • Launching Jupyter Lab on a Remote Cluster
      • Running on a Remote Host's Head Node
      • Running on a Remote Host's Compute Node

Badges

CI
Docs
Package
License

Overview

Jupyter-forward simplifies the process of running jupyter lab on a remote machine by performing the following tasks on behalf of the users:

1. Log into a remote cluster/resource via the SSH protocol.
2. Launch Jupyter Lab on the remote cluster.
3. Port forward Jupyter Lab session back to your local machine!
4. Opening the port forwarded Jupyter Lab session into your local browser

Usage

❯ jupyter-forward --help
Usage: jupyter-forward [OPTIONS] COMMAND [ARGS]...

  Jupyter Lab Port Forwarding Utility

Options:
  --install-completion  Install completion for the current shell.
  --show-completion     Show completion for the current shell, to copy it or
                        customize the installation.

  --help                Show this message and exit.

Commands:
  end     Stops the running Jupyter Lab server.
  resume  Resumes an already running remote Jupyter Lab session.
  start   Starts Jupyter lab on a remote resource and port forwards session...

Launching Jupyter Lab on a Remote Cluster

jupyter-forward provides functionality to launch a jupyter lab session on a remote cluster via the start command:

❯ jupyter-forward start --help

Usage: jupyter-forward start [OPTIONS] HOST

  Starts Jupyter lab on a remote resource and port forwards session to local
  machine.

Arguments:
  HOST  [required]

Options:
  --port INTEGER                  The local port the remote notebook server
                                  will be forwarded to. If not specified,
                                  defaults to 8888.  [default: 8888]

  --conda-env TEXT                Name of conda environment on the remote host
                                  that contains jupyter lab

  --notebook-dir TEXT             The directory on the remote host to use for
                                  notebooks

  --port-forwarding / --no-port-forwarding
                                  Whether to set up SSH port forwarding or not
                                  [default: True]

  -i, --identity PATH             Selects a file from which the identity
                                  (private key) for public key authentication
                                  is read.

  -c, --launch-command TEXT       Custom command to run before launching
                                  Jupyter Lab. For instance: "qsub -q regular
                                  -l select=1:ncpus=36,walltime=00:05:00 -A
                                  AABD1115"

  --help                          Show this message and exit.

Note: The start command will prompt you for your password.

Running on a Remote Host's Head Node

For instance, here is how to start a jupyter lab server running on port 9999 on one of Cheyenne's login nodes:

❯ jupyter-forward start mariecurie@cheyenne.ucar.edu

Running on a Remote Host's Compute Node

To launch jupyter lab on a remote host's compute node, the user needs to specify the --launch-command option. The launch command is meant to submit a job on the remote host's queueing system. Once the job is up and running, jupyter lab is launched on the compute node and the session is port-forwarded to the user's local machine.

Here is a couple examples:

• Launch Jupyter Lab on a remote system that uses PBS job scheduler

❯ jupyter-forward start mariecurie@cheyenne.ucar.edu --launch-command "qsub -q regular -l select=1:ncpus=36,walltime=00:05:00 -A AABD1115"

• Launch Jupyter Lab on a remote system that uses Slurm job scheduler

❯ jupyter-forward start mariecurie@casper.ucar.edu --launch-command "sbatch -A AABD1115 -t 00:05:00"