Manage Jupyter notebook servers

• To run a Jupyter server just execute any code cell. When you initiate cell execution, DataSpell launches a Jupyter server on the local host using any available port (by default, it is the 8888 port). You can switch to the Jupyter Server tool window to preview server's configuration details.

Once the server is launched, it is shown as a managed server in the list of the servers in the Jupyter toolbar. You can also see the automatically created server kernel in the list of kernels. This kernel is based on the Python interpreter configured for the directory.

1. Create an SSH Python interpreter as described in Configure an interpreter using SSH.

   warning

   You cannot use an SSH interpreter as a default interpreter for the DataSpell workspace. Configure it for a attached directory instead.

2. To run a Jupyter server just execute any code cell. DataSpell creates SSH tunnels, copies project files, and launches a Jupyter server on the remote host.

   Once the server is launched, it is shown as a managed server in the list of the servers in the Jupyter toolbar.

1. Click the icon on the toolbar of the Workspace tool window to establish a connection to a Jupyter server.

2. In the New Jupyter Connection dialog, select the connection type:

   • Start a local Jupyter server: run a Jupyter server in a local directory that will be attached to your workspace.

   • Connect to a running local Jupyter server: establish a connection to any locally run Jupyter server. The option is enabled if there is at least one active Jupyter server on your machine. Run jupyter notebook list in the Terminal window to check if there are any.

   • Connect to Jupyter server using URL: establish a connection to a remote Jupyter server. The target URL should contain a server name or its address, and the access token.

   

   Once the connection has been established, the server and its structure are shown in the Workspace tool window.

   

You can establish connection to a Jupyter server through OAuth authentication using the JupyterHub API token.

1. Click the icon on the toolbar of the Workspace tool window.

2. Select Connect to Jupyter server using URL and enter the target Jupyter server address in the Server URL field. Click Add.

   

   Click the Link to the token page link.

3. You will be prompted to login into GitHub. Click Sign in with GitHub.

   

   Note that although GitHub is used in this example, it is just one of the supported OAuth providers (see the complete list in JupyterHub documentation).

4. Confirm your authorization on GitHub or provide your credentials.

   

5. The token page should open in the browser. Click the Request new API token button and copy the token that appears in the You new API token area.

   

6. Paste the value into the Token field of the Authenticating to JupyterHub dialog. Also, specify the system username that will be used to run a notebook process.

   note

   Note that this should not be an OAuth provider login. Contact the administrator of your JupyterHub server if you don’t know the system username. For more information, refer to JupyterHub documentation.

   

   Click OK and then Add to complete the task.

• To stop any running server, switch to the Jupyter Server tool window and click the icon. Preview the status in the Server Log window.

Once you have shut down the server, the current session is terminated. When you start the server next time using the icon, execution results for all previous sessions and all notebooks will be lost.

• You might want to refresh your calculations without shutting down the entire server and affecting any other notebooks. To restart the currently running kernel, click on the Jupyter notebook toolbar. You can then view the kernel status in the Server Log window:

  

  You can find other kernel specific commands in the Kernel menu of the DataSpell main menu.

1. Select Configure Jupyter Server in the list of the Jupyter servers.

   

2. Then select Use Managed Server. By default, the server will use the project Python interpreter. If necessary, select another local interpreter from the list.

   

3. In the Command line arguments field, you can do the following:

   • Include a custom working directory

   • Make the server accessible on the local network

   • Run the server as root

   • Set a password to access to the server

   • Run JupyterLab instead of Jupyter Notebook

   • Change the automatically detected port.

   For example, use the following command-line arguments to run the Jupyter Notebook server at port 9090 without opening a browser:

   

4. Environment variables can be set by creating different variables and assigning values to them.

   

5. Once done with configuring, click Apply and OK.

6. Then execute any code cell to run the managed server.

1. Select Configure Jupyter Server in the list of the Jupyter servers.

   

2. Then select Configured Server and add the server's path. It consists of a URL and a token.

   

3. Once done with configuring, click Apply and OK.

4. Then execute any code cell to connect to the running configured server.

• If you see the following warning, the kernel of the newly configured server doesn't match your current Python interpreter. For example, it might have a different set of the installed packages.

  

  You can register your Python interpreter as a kernel on the configured server by clicking the corresponding link. After that you can see it in the list of the kernels for the configured server.