.. _tutorials-conda-jupyter:

Custom Conda Environments in JupyterLab
=======================================

If you are used to working with Ipython notebooks and are now migrating your workflow from a local machine to the CoSTAR cluster, using JupyterLab is a great way to get comfortable.

This guide demonstrates how to install your own version of Miniconda, create a custom Python environment, and make that environment available as a "Kernel" inside the cluster's Open OnDemand JupyterLab portal.


1. Connect and install Miniconda
--------------------------------
First, SSH into the CoSTAR login node:

.. code-block:: bash

   ssh ab1234@costar-login01

Next, download and run the Miniconda installer in your home directory. Follow the on-screen prompts (pressing Enter to scroll through the license, typing ``yes`` to accept, and ``yes`` to initialize Conda).

.. code-block:: bash

   wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
   bash Miniconda3-latest-Linux-x86_64.sh

Once installed, **log out and log back in** to ensure Conda is activated in your terminal. You should see ``(base)`` next to your command prompt.

.. dropdown:: Troubleshooting: No (base) prompt?
   :icon: alert

   If you log back in and do not see the ``(base)`` prompt, your cluster profile might not be set up to read your ``.bashrc`` file automatically. Run the following command once to fix this:

   .. code-block:: bash

      echo -e "\nif [ -f ~/.bashrc ]; then\n    source ~/.bashrc\nfi\n" >> ~/.bash_profile

   Then, simply run ``source ~/.bashrc`` to activate Conda for your current session.

2. Create your custom environment
---------------------------------
Now, create a new environment. For this example, we will call it ``myenv`` and install Python, numpy, and a crucial package called ``ipykernel``.


.. code-block:: bash

   conda create -n myenv python=3.13 numpy ipykernel -c conda-forge
   conda activate myenv

3. Link the environment to Jupyter
----------------------------------
With your environment activated, run the following command to register it with Jupyter. This creates a tiny file in your home directory that Open OnDemand reads when it starts up.

.. code-block:: bash

   python -m ipykernel install --user --name=myenv --display-name="Python (myenv)"

4. Launch JupyterLab via Open OnDemand
--------------------------------------
You are now ready to use the web portal!

1. Open your web browser and navigate to the `CoSTAR Open OnDemand portal <https://costar-ood.surrey.ac.uk/>`__.
2. Go to **all available apps Apps** > **JupyterLab**.
3. Request your resources (e.g. 2 CPU cores, 4 hours, 8GB of Memory, etc) and click **Launch**.
4. Once your session starts, click **Connect to Jupyter**.

When the JupyterLab interface loads, open a new Notebook. In the top right corner (or in the Launcher menu), you will now see **Python (myenv)** available as a kernel option. Select it, and you are ready to code using the cluster's compute power!

For an introduction to JupyterLab please visit :ref:`Jupyter Lab Introduction <software-jupyterlab>`.