CLEAR Jupyter & Web-Based Computing Guide

This section explains how to install and run JupyterLab on a Windows computer using Miniconda.

Install Jupyter

Before installing Jupyter, make sure Python 3 and Miniconda are installed. See the Miniconda Python 3 Installation on Windows instructions.

Open the Anaconda Prompt (miniconda3) and install Jupyter and JupyterLab:

python -m pip install jupyter jupyterlab

The installation may take several minutes to complete.

Run JupyterLab

Additional Python libraries may be required depending on your course or project. Your instructor may provide a list of required libraries.

To start JupyterLab, run:

python -m jupyter lab

To open an existing Jupyter Notebook file, run:

python -m jupyter lab <file>.ipynb

Be sure to save your work regularly. When finished, shut down or quit the Jupyter server to release the resources it is using.

Jupyter Notebook and JupyterLab provide browser-based environments for interactive computing, programming, coursework, and data analysis.

Verify Miniconda

For some courses, Miniconda may already be installed in your CLEAR home directory. Connect to CLEAR using SSH and run:

ls -la ~/miniconda3
env | grep -i conda

If Miniconda is installed and configured, these commands should display the Miniconda directory and related environment information.

Install Jupyter

With Miniconda available, install Jupyter with:

conda install jupyter -y

Verify the Installation

Verify that Jupyter is available:

which jupyter
jupyter --version

Running Jupyter on CLEAR

Running Jupyter on CLEAR requires an SSH tunnel between your local computer and the CLEAR system. Jupyter runs on the remote CLEAR system while your local web browser connects to it through the encrypted SSH tunnel.

You must use the same port number when creating the SSH tunnel and starting the Jupyter server.

macOS and Linux

Create the SSH Tunnel

Choose a port number for your Jupyter session. Your instructor may assign a port, or you may select an available high-numbered port.

From a terminal on your local computer, run:

ssh -L <port>:localhost:<port> <NetID>@ssh.clear.rice.edu

Replace <port> with your selected port number and <NetID> with your Rice NetID. Complete the required authentication process.

Keep this SSH session open while using Jupyter.

Start Jupyter Notebook

After connecting to CLEAR through the SSH tunnel, start Jupyter Notebook using the same port:

jupyter notebook --no-browser --port=<port>

Jupyter will display one or more local URLs containing an authentication token. The URL will look similar to:

http://localhost:<port>/?token=<your-token>

Use the URL generated by your own Jupyter session. Do not use an example token from documentation.

Connect to Jupyter

Open a web browser on your local computer and paste the URL generated by Jupyter into the browser address bar.

If the SSH tunnel and Jupyter server are running correctly, the Jupyter interface should appear in your browser.

Windows

Windows users can create the required SSH tunnel using Windows Subsystem for Linux (WSL), PuTTY, MobaXterm, or another SSH client that supports local port forwarding.

Windows Subsystem for Linux

If you use WSL and have the OpenSSH client available, you can follow the macOS and Linux SSH tunnel instructions above.

PuTTY Configuration

To configure an SSH tunnel using PuTTY:

1. Start PuTTY.
2. Select Session.
3. Enter ssh.clear.rice.edu in the Host Name field.
4. Enter a descriptive name such as CLEAR SSH Tunnel in the Saved Sessions field.
5. Select Save.

Next, configure local port forwarding:

1. Navigate to Connection > SSH > Tunnels.
2. Enter your selected port number in the Source port field.
3. Enter localhost:<port> in the Destination field.
4. Select Local if it is not already selected.
5. Select Add.

Return to Session and save the configuration again so the tunnel settings are preserved.

Open the saved session and authenticate using your Rice NetID credentials and any required authentication prompts.

After connecting, verify Jupyter:

jupyter --version

Then start Jupyter using the same port configured in the PuTTY tunnel:

jupyter notebook --no-browser --port=<port>

Open the URL generated by Jupyter in your local web browser.

MobaXterm Configuration

MobaXterm also supports SSH tunneling and local port forwarding. For general MobaXterm configuration, see MobaXterm with X11 Forwarding, Duo, and SCP Support.

Use the MobaXterm tunneling tool to configure local port forwarding between your local computer and the Jupyter port on the CLEAR system.

As with all other connection methods, make sure the local tunnel port and the port used to start Jupyter are the same.

Troubleshooting

Connection Refused

If you receive an error similar to:

channel #: open failed: connect failed: Connection refused

Verify that the Jupyter server is running and that you used the same port number when configuring the SSH tunnel and starting Jupyter.

Julia can be used with Jupyter Notebook or JupyterLab on CLEAR. This configuration combines Julia, Jupyter, Miniconda, SSH tunneling, and a local web browser.

Required Components

• Julia and juliaWjup.sh: Provide the Julia environment and related packages.
• SSH: Provides remote access to CLEAR and creates the tunnel between your browser and the remote Jupyter server.
• Miniconda and Jupyter: Provide the Python and Jupyter environment in your CLEAR home directory.
• Web browser: Displays the Jupyter interface on your local computer.

juliaWjup.sh

The juliaWjup.sh wrapper configures environment variables needed to combine the system-wide Julia installation, your personal Julia environment, and your Miniconda Jupyter installation.

For help, run:

juliaWjup.sh -h

To display the Julia version used by the wrapper, run:

juliaWjup.sh -- --version

Verify Miniconda

To check whether Miniconda is installed in your CLEAR home directory, run:

cd
ls -lad miniconda3

If the directory does not exist and your course requires this environment, submit a request through the TS&S Service Desk and indicate that you need Miniconda with Jupyter and Julia installed in your CLEAR home directory.

Start Julia and Jupyter

Open an SSH session to CLEAR:

ssh <NetID>@ssh.clear.rice.edu

Start the Julia environment:

juliaWjup.sh

From the Julia shell, you can use IJulia to start the Jupyter Notebook server:

using IJulia
notebook(detached=true)
run(`$(IJulia.find_jupyter_subcommand("")[1]) notebook list`)

The final command displays the URL and port number for the running Jupyter server. The output will contain a URL similar to:

http://localhost:<port_num>/?token=<your-token>

Keep this SSH session open.

Create the SSH Tunnel

Open a second terminal on your local computer and create an SSH tunnel using the port number displayed by Jupyter:

ssh -L <port_num>:localhost:<port_num> <NetID>@ssh.clear.rice.edu

Keep the SSH tunnel session open.

Connect from Your Browser

Open a browser on your local computer and paste the URL generated by your Jupyter server into the address bar.

If prompted for a token, use the unique token generated by your Jupyter session.

After signing in, select the appropriate Julia kernel to create a new Julia notebook.

When Finished

• Save your notebook and other work.
• Shut down your running notebooks.
• Shut down the Jupyter server.
• Close the SSH tunnel session.
• Exit Julia using exit().
• Close your remaining SSH session.

Shutting down unused Jupyter and Julia processes helps free CLEAR system resources for other users.

Julia is available on the CLEAR systems through a wrapper script and through the Julia application directly.

Using julia.sh

The julia.sh wrapper provides access to a preconfigured Julia environment with a collection of packages used for scientific computing and optimization.

To start the wrapper, run:

julia.sh

For extended help, run:

julia.sh -H

Example Project

To create and start a Julia project:

julia.sh -n Project
cd Project
julia.sh

Using Julia Directly

If you need to use a specific Julia installation directly, configure your PATH for that Julia version.

For example:

export PATH=/opt/julia-1.10.4/bin:${PATH}

This change applies only to the current terminal session. If you open another SSH session, you must run the command again.

After configuring the path, verify Julia with:

which julia
julia --version

Then start Julia with:

julia

Using a Wrapper Script

You can also create a shell script that configures the required Julia environment before running your Julia program.

For example, create a simple Julia program:

cat > hello.jl <<'EOF'
# This program prints Hello, world!
print("Hello, world!\n")
EOF

Create a wrapper script:

cat > run-app.sh <<'EOF'
#!/usr/bin/env bash

[[ ${DEBUG} ]] && set -xvu

PATH=/opt/julia-1.10.4/bin:${PATH}
JULIA='julia'

${JULIA} --version
${JULIA} hello.jl
EOF

Make the script executable:

chmod u+x run-app.sh

Run the script:

./run-app.sh

For verbose shell output, run:

DEBUG=true ./run-app.sh

Permanent PATH Configuration

In most cases, students should avoid permanently configuring a specific Julia version unless necessary. A permanent configuration may affect other courses or applications that require a different version.

If you need to determine your current shell, run:

echo $SHELL

Common shell initialization files include:

• sh, bash, or ksh: ~/.profile
• csh or tcsh: ~/.login
• zsh: ~/.zprofile

For Bourne-compatible shells such as Bash, the Julia path can be added with:

export PATH=/opt/julia-1.10.4/bin:${PATH}

Log out and log back in after modifying your shell initialization file.

If you need to change your default shell, see Modify Your Default Linux Shell.

The julia.sh environment includes a large collection of Julia packages used for scientific computing, numerical analysis, optimization, data analysis, visualization, and related coursework.

Because the available package collection may change as the CLEAR Julia environment is updated, users should verify required packages from within their Julia environment.

If your course or project requires a package that is not available, contact the TS&S Service Desk or your course instructor for assistance.

Quarto is an open-source scientific and technical publishing system that can be used with Jupyter notebooks and other computational environments.

These instructions focus on using Quarto with Windows, Miniconda, and Jupyter.

Before proceeding, make sure Miniconda and Jupyter are installed. See:

• Miniconda Python Installation on Windows
• Jupyter on Windows

What Is Quarto?

Quarto supports the creation of reproducible scientific and technical documents in formats such as HTML, PDF, and Microsoft Word.

For current information, installation instructions, and documentation, visit the Quarto website.

Install Quarto

Because Quarto versions change over time, use the current installer and installation instructions provided by the official Quarto website rather than downloading a version-specific installer from this document.

After installing Quarto, open the Anaconda Prompt (miniconda3).

If your project requires Matplotlib and Plotly, install them with:

python -m pip install matplotlib plotly

Using Quarto with Jupyter

Start JupyterLab with:

python -m jupyter lab

To open a specific notebook, run:

python -m jupyter lab hello.ipynb

Quarto can render a Jupyter notebook to different output formats. For example:

quarto render hello.ipynb --to html
quarto render hello.ipynb --to docx

For current tutorials and examples, see the Quarto Jupyter tutorial.

Additional documentation is available in the Quarto Guide.

Quarto and Visual Studio Code

If you use Visual Studio Code with a Miniconda environment, start Visual Studio Code from an Anaconda Prompt so the application inherits the appropriate environment.

1. Open an Anaconda Prompt.
2. Verify that the prompt shows the expected Conda environment, such as (base).
3. Run code to start Visual Studio Code.
4. Open a terminal in Visual Studio Code and verify that the expected Python or Conda environment is active before running Jupyter or Quarto commands.

You can then continue working with Python, Jupyter, and Quarto from within Visual Studio Code.