/ cryosparc tips

Access the cryoSPARC UI remotely via SSH-tunneling

By default, cryoSPARC user interface pages are served by a web server running on the same machine where cryoSPARC is installed, at port 38000. This web server is responsible for displaying datasets, experiments, streaming real time results, user accounts, updating, etc.

Often, the compute server running cryoSPARC may be behind a firewall with no direct access from the outside world to port 38000, but still accessible via SSH. When you want to access cryoSPARC from home or elsewhere to be able to run experiments and view results, it can be convenient to connect to the web server via an SSH tunnel. This post assumes you are trying to access cryoSPARC from a Linux/UNIX/MacOS local system.

When you can connect to the compute node with a single SSH command

This scenario assumes your network setup looks like this:

                internet                    
[ localhost ]==============[ firewall | remote host ]

CryoSPARC is running on the remote host, and the firewall only allows SSH connections (port 22). Since you can directly ssh into the compute node, use the following steps:

  1. Set up SSH keys for password-less access (only if you currently need to enter your password each time you ssh into the compute node).

    1. If you do not already have SSH keys generated on your local machine, use ssh-keygen to do so. Open a terminal prompt and type
ssh-keygen -t rsa -N "" -f $HOME/.ssh/id_rsa

Note: this will create an RSA key-pair with no passphrase in the default location.

  1. Copy the RSA public key to the remote compute node for password-less login:
ssh-copy-id remote_username@remote_hostname

Note: remote_username and remote_hostname are your username and the hostname that you use to SSH into your compute node. This step will ask for your password.

  1. Start an SSH tunnel to expose port 38000 from your compute node to your local machine.
ssh -N -f -L localhost:38000:localhost:38000 remote_hostname

Note: the -f flag tells ssh to run in the background, so you can close the terminal window after running this command, and the tunnel will stay open.

  1. Now, open your browser (Chrome) and navigate to http://localhost:38000. You should be presented with the cryoSPARC login page.
When you have to SSH through multiple servers to reach your cryoSPARC compute node

This scenario assumes your network setup looks like this:

            internet                      LAN
[ localhost ]=====[ firewall | sshserver ]===[ firewall | remotehost ]

CryoSPARC is running on the remote host, behind an ssh server, both of which have firewalls. The firewalls only allow SSH connections (port 22). In this case, you can use multi-hop SSH to create a tunnel to the remote host to expose port 38000:

  1. Set up SSH keys for password-less access from localhost -> ssh server
    1. If you do not already have SSH keys generated on your local machine, use ssh-keygen to do so. Open a terminal prompt and type
ssh-keygen -t rsa -N "" -f $HOME/.ssh/id_rsa

Note: this will create an RSA key-pair with no passphrase in the default location.

  1. Copy the RSA public key to the ssh server for password-less login:
ssh-copy-id ssh_username@ssh_server

Note: ssh_username and ssh_server are your username and the hostname that you use for SSH from the outside world. This step will ask for your password.

  1. Set up SSH keys for password-less access from ssh server -> remote host
    Note: this step is not necessary if you can already ssh without a password to the compute node from the ssh server.
    1. If you do not already have SSH keys generated on your ssh server, use ssh-keygen to do so. Open a terminal prompt, then
      ssh ssh_server
      Once logged into the ssh server:
      ssh-keygen -t rsa -N "" -f $HOME/.ssh/id_rsa
      Note: this will create an RSA key-pair with no passphrase in the default location.
    2. Copy the RSA public key to the remote compute node for password-less login:
    ssh-copy-id remote_username@remote_hostname
    

Note: remote_username and remote_hostname are your username and the hostname that you use to SSH into the compute node itself. This step will ask for your password.

  1. Set up a multi-hop connection from your local host to the remote host. To do this, open the file ~/.ssh/config (or create it if it doesn't exist) and add the following lines:

     Host *
             ServerAliveCountMax 4
             ServerAliveInterval 15
    
     Host local_name_for_remote_host
             HostName remote_hostname
             User remote_username
             ProxyCommand ssh -q ssh_username@ssh_server -W %h:%p  
    

Replace local_name_for_remote_host with a short name you will use to refer to the remote compute node. Replace remote_username and remote_hostname with the actual user/hostname of the compute node that you would use to connect to it from the ssh server. Replace ssh_username and ssh_server with the user/hostname of the ssh server. Save the file.

  1. Start an SSH tunnel to expose port 38000 from your compute node to your local machine.
ssh -N -f -L localhost:38000:localhost:38000 local_name_for_remote_host

Note: the -f flag tells ssh to run in the background, so you can close the terminal window after running this command, and the tunnel will stay open.

  1. Now, open your browser (Chrome) and navigate to http://localhost:38000. You should be presented with the cryoSPARC login page.