Accessing the CryoSPARC User Interface

Viewing the user interface locally and from home

The CryoSPARC user interface is served by a web server running on the same computer where CryoSPARC is installed, at the base port specified during installation. This web server is responsible for displaying datasets, experiments, streaming real time results, user accounts, updating, etc.

When you install CryoSPARC, you will be shown details on how to access the interface using the configuration you've provided.

cryosparcuser@csserver:~$ cryosparc_master/bin/cryosparcm start
Starting CryoSPARC System master process...
CryoSPARC is not already running.
configuring database...
    configuration complete
database: started
database OK
command_core: started
    command_core connection succeeded
    command_core startup successful
command_vis: started
command_rtp: started
    command_rtp connection succeeded
    command_rtp startup successful
app: started
app_api: started
-----------------------------------------------------

CryoSPARC master started. 
 From this machine, access CryoSPARC and CryoSPARC Live at
    http://localhost:61000

 From other machines on the network, access CryoSPARC and CryoSPARC Live at
    http://csserver.lab:61000


Startup can take several minutes. Point your browser to the address
and refresh until you see the CryoSPARC web interface.

Given the example above, one may connect to the CryoSPARC user interface

• using a browser running on the CryoSPARC master computer: with URL http://localhost:61000

• using a browser running on the same network as the CryoSPARC master computer: with URL http://csserver.lab:61000

• using a browser running on another network, the URL depends on the network access method (see below)

Typical network setup for a CryoSPARC user

When you are working from a remote network, you will usually not have direct access to the master node to use CryoSPARC as you usually would.

Often, the master CryoSPARC server may be behind a firewall, within a local network (LAN) at your institution. Only other machines that are on the same local network can connect to the master server at port 61000.

VPN Access

Most institutions offer Virtual Private Network (VPN) capability which can allow you to connect to the institution's local network as if you are physically present at the office. There are different types of VPN connections, but most will allow you, once logged in, to connect to the CryoSPARC master server as you usually would, using your browser.

In some cases, your VPN may only allow certain types of connections, or your institution may allow for access over only some secure ports to your CryoSPARC master server, without a VPN log in. In both of these cases, if you are able to find a way to connect to your CryoSPARC master server using SSH, it is still possible to use CryoSPARC, even if you cannot connect to port 61000 as you usually would.

SSH Access and Tunneling

When you want to access CryoSPARC from home or elsewhere to be able to run jobs and view results, it can be convenient to connect to the web server via an SSH tunnel. SSH tunneling is a method of transporting arbitrary networking data over an encrypted SSH connection.

SSH is a standard for secure remote logins and file transfers over untrusted networks. It also provides a way to secure the data traffic of any given application using port forwarding, basically tunneling any TCP/IP port over SSH. This means that the application data traffic is directed to flow inside an encrypted SSH connection so that it cannot be eavesdropped or intercepted while it is in transit. Source: SSH Tunnel

You may need to use a Virtual Private Network (VPN) client to connect to your institution's VPN in order to access the local network.

SSH Local Port Forwarding

Supposing an example scenario where

• CryoSPARC is installed on a computer with hostname csserver.lab

• the web application port is configured to "listen" at port number 61000

• you have ssh access to the myname account on csserver.lab

• the port 62222 on the "local" computer that runs your web browser is not currently in use

you can establish a tunnel between the local computer and the CryoSPARC server with the command

ssh -L 62222:localhost:61000 [e-mail]

If you do not have ssh access to the CryoSPARC server, but do have ssh access to another computer (sshserver.lab for example) that itself can access the web application port on the CryoSPARC server, you can instead establish the tunnel with the command

ssh -L 62222:csserver.lab:61000 [e-mail]

In both examples, the first port number

• is a freely chosen port on the local ("browser") computer that must not already be in use

• determines the <portnumber> portion in the http://localhost:<portnumber> URL to which you will point your browser.

The second port number in both examples is prescribed by the web application port number configured during CryoSPARC installation. Based on the two ssh examples above, you would point your browser to http://localhost:62222

CryoSPARC UI login page

More complex SSH requirements and configurations

If you need to hop over one or more "jump" hosts to access the CryoSPARC server or alternative "tunnel" server, please refer the OpenSSH wikibook for suggested ~/.ssh/config configurations.

Reverse Proxy

Refer to the following guide for more information on hosting the CryoSPARC web application via a reverse proxy server:

(Optional) Hosting CryoSPARC Through a Reverse Proxy

Appendix

Appendix A: Setting up password-less SSH access to a remote workstation

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 on your local machine, and enter:

   ssh-keygen -t rsa -N "" -f $HOME/.ssh/id_rsa

   Note: this will create an RSA key-pair with no passphrase.

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 your compute node. This step will ask for your password.

Appendix B: Using SSH Forwarding with compression to reduce data usage

Supply -C to the port tunnelling command to request compression of all data. This can help when downloading maps from the CryoSPARC UI, as masks can be greatly compressed. From man ssh:

-C           Requests compression of all data (including stdin, stdout, stderr, 
             and data for forwarded X11, TCP and UNIX-domain connections).  
             The compression algorithm is the same used by gzip(1), and the 
             “level” can be controlled by the CompressionLevel option for 
             protocol version 1.  Compression is desirable on modem lines and 
             other slow connections, but will only slow down things on fast 
             networks.

For example:

ssh -N -f -L localhost:62222:localhost:61000 remote_hostname -C

Appendix C: Using Hardware Accelerated OpenSSH Ciphers

If your system supports Intel or AMD AES-NI, you can take advantage of hardware accelerated ciphers that dramatically improve the performance of your SSH connection. To find out if your system supports this, follow this tutorial.

If your system has these features enabled, supply the argument -o Ciphers=[e-mail] or -o Ciphers=[e-mail] (depending on what your system supports, but AES 256 is preferred) to the port forwarding command. For example:

ssh -N -f -L localhost:62222:localhost:61000 remote_hostname -C -o Ciphers=[e-mail]

Appendix D: Custom SSL Certificate Authority Bundle

cryoSPARC requires internet access from the main process to verify your license and perform updates. At minimum, CryoSPARC should have access to our license server at https://get.cryosparc.com/.

On some older systems, or if your system is behind a HTTP proxy, CryoSPARC may have trouble getting the required SSL certificates to validate this requires. If you have a Certificate Authority (CA) bundle on your system, you may specify its path for CryoSPARC to use and apply.

Add the following line to cryosparc_master/config.sh (substitute /path/to/cabundle with the path to the CA bundle on your system):

export REQUESTS_CA_BUNDLE="/path/to/cabundle"