Running a Jupyter notebook on a remote machine

Credit where credit is due

This page is based on this post by L. J. Miranda .

How do I run a Jupyter notebook on a remote machine while controlling it from a browser?

The wrong way to do this is to ssh to the remote machine with X windows forwarding and start the browser on the remote machine. In principle this will work but X can be painfully slow over a network (X is a 1980s bitmap system).

The right way to do this is to use port forwarding.

Configuring port forwarding

These instructions assume you have SSH installed on your local machine.

1. On your local machine, add the following to the SSH config file ($HOME/.ssh/config).

             Host label_for_the_connection
                 HostName name_of_the_remote_machine
                 User your_userid_on_the_remote_machine
                 LocalForward port_on_remote_machine localhost:post_on_local_machine
           

   Henceforth we will work with a concrete example from my SSH config file:

             Host notebooks7
                 HostName th121-7.cs.wm.edu
                 User rmlteach
                 LocalForward 8888 localhost:8888
           

2. On your local machine, execute the following at the command line:

             ssh -Nf notebooks7
           

3. On the remote machine, (optionally) cd to the directory with the notebook you wish to run, and execute the following at the command line:

             jupyter notebook --no-browser --port=8888 &
           

   (In general you would use port_on_remote_machine from your SSH config file as the port number.) You will see a bunch of output from Jupyter at the command line. Here are the important lines to look for:

             To access the notebook, open this file in a browser:
                 file:///home/rmlteach/.local/share/jupyter/runtime/nbserver-3323606-open.html
             Or copy and paste one of these URLs:
                 http://localhost:8888/?token=b682e7bdbade2fed14450731015f5aeeefb74cfe778441c3
              or http://127.0.0.1:8888/?token=b682e7bdbade2fed14450731015f5aeeefb74cfe778441c3
           

4. On your local machine, fire up a browser and go to either the localhost or 127.0.0.1 URL from the previous step. You should see Jupyter notebook.

Port forwarding if you are off-campus

The easiest way to manage off-campus port forwarding is to use the College's VPN. The VPN takes care of negotiating the bastion host W&M uses to controls network access from off-campus.

Troubleshooting

If either of the two ports (on the local machine and the remote machine) is in use this approach won't work. This sometimes happens if a previous incarnation of Jupyter notebook is hanging around. You can figure out what process has the port open with lsof -i :8888 (or whatever port you are using). If it is one of your processes, you can kill it and start the forwarding process anew.

The command lsof is "list open files". Unix/Linux treats lots of things, including ports, as having file-like properties. This gives a common way of interacting with them–opening them, reading from them, writing to them, and closing them.