Jupyter Workflow
================

This chapter describes the recommended workflow for using JupyterLab on
the server.

Overview
---------

The workflow consists of five steps:

1. Create a Python virtual environment (only once).
2. Start a Jupyter server on the remote machine.
3. Create an SSH tunnel from the local machine.
4. Open JupyterLab in a local web browser.
5. Upload and execute notebooks.

Step 0: Create a Dedicated Jupyter Environment
----------------------------------------------

This step is performed only once.

Create a virtual environment:

.. code-block:: bash

   python3 -m venv ~/venvs/jupyter

Activate it:

.. code-block:: bash

   source ~/venvs/jupyter/bin/activate

Install JupyterLab:

.. code-block:: bash

   pip install jupyterlab

Verify the installation:

.. code-block:: bash

   jupyter lab --version

Step 1: Start the Jupyter Server
--------------------------------

Connect to the server:

.. code-block:: bash

   ssh username@server.example.edu

Activate the environment:

.. code-block:: bash

   source ~/venvs/jupyter/bin/activate

Launch JupyterLab:

.. code-block:: bash

   jupyter lab --no-browser --ip=127.0.0.1 --port=8888

A message similar to the following will appear:

.. code-block:: text

   http://127.0.0.1:8888/lab?token=<TOKEN>

Keep this terminal open.

The Jupyter server will continue running in this session.

Step 2: Create an SSH Tunnel
----------------------------

Open a second terminal on your local computer.

Create a tunnel:

.. code-block:: bash

   ssh -L 8888:127.0.0.1:8888 username@server.example.edu

After authentication, leave this terminal open.

The local port 8888 is now connected to the Jupyter server running on
the remote machine.

Step 3: Open JupyterLab
-----------------------

Open a web browser and visit:

.. code-block:: text

   http://localhost:8888/tree

If prompted, paste the token displayed when the Jupyter server was
started.

Alternatively, use the complete URL displayed by Jupyter:

.. code-block:: text

   http://127.0.0.1:8888/lab?token=<TOKEN>

You should now see the JupyterLab interface.

Step 4: Upload Files
--------------------

JupyterLab provides a graphical interface for managing files.

To upload a notebook or script:

1. Open the file browser panel.
2. Navigate to the desired directory.
3. Click the ``Upload Files`` button.
4. Select one or more files from your computer.
5. Wait until the upload completes.

Alternatively, files can be dragged directly into the file browser.

After the upload finishes, the files become immediately available on the
server filesystem.

Opening Notebooks
-----------------

Double-click a notebook file:

.. code-block:: text

   *.ipynb

to open it in JupyterLab.

Cells can be executed individually or sequentially.

Kernel Management
-----------------

To restart a kernel:

.. code-block:: text

   Kernel → Restart Kernel

To interrupt a computation:

.. code-block:: text

   Kernel → Interrupt Kernel

Stopping Jupyter
----------------

Return to the terminal where Jupyter was launched.

Press:

.. code-block:: text

   Ctrl+C

and confirm the shutdown.