# Persistent Python Environments

By default, SciServer Compute containers are **ephemeral**. When you restart a
container, the jupyerlab filesystem (including `~/.conda` or `~/.miniforge3`) is
reset. Any packages you installed directly into the base environment or a local
environment will disappear.

To avoid reinstalling packages every time you launch a container, you should
store your **Mamba environments** somewhere in your User Storage.

## Overview

1. **Create** the environment in your persistent storage.
2. **Register** the environment as a Jupyter Kernel (so it appears in the
   launcher).
3. **Reload** the environment in any new container.

---

## Step 1: Create a Persistent Environment

Instead of letting Mamba use its default _prefix_ location, we explicitly tell
it to create the environment folder inside your mounted personal storage.

As explained under [Files and Volumes](../files_and_volumes.md), you have 2
areas for personal data: Storage and Temporary. For the example below we'll
create a folder under Temporary, but you can choose any location controled by
you.

Run this command inside your terminal:

```bash
# Create an env named 'my-analysis' inside your persistent folder
# This example automatically adds a few packages to the new environment on creation
mamba create -p ~/workspace/Temporary/$SCISERVER_USER_NAME/scratch/envs/my-analysis python=3.12 ipykernel astropy numpy pandas
```

> **What just happened?** You used the `-p` (prefix) flag instead of `-n`
> (name). This forces Mamba to write the environment files to a path that
> survives container restarts.

---

## Step 2: Make Jupyter Aware of Your Environment

Creating the environment isn't enough; JupyterLab needs to know it exists to run
notebooks against it. You need to install a **kernel spec**.

1. **Activate your new environment:**

    ```bash
    # Activate using the full path
    mamba activate ~/workspace/Temporary/$SCISERVER_USER_NAME/scratch/envs/my-analysis
    ```

2. **Install `ipykernel`:**

    ```bash
    # In case you didn't add it already
    mamba install ipykernel
    ```

3. **Register the kernel:**

    ```bash
    python -m ipykernel install --user --name=my-analysis --display-name "My Analysis"
    ```

4. **Reload page:**

   A simple browser reload makes jupyter aware of this new kernel and appear as
   an option in your list of kernels.

> **Note:** The `--user` flag writes the kernel specification to
> `~/.local/share/jupyter/kernels`. **This directory is ephemeral**, but that is
> okay. The kernel spec is just a small text file pointing to your persistent
> environment. You can easily recreate it (see Step 3).

---

## Step 3: Reloading in a New Container

When you launch a fresh container, your environment folder is still there at
`~/workspace/Temporary/$SCISERVER_USER_NAME/scratch/envs/my-analysis`, but
Jupyter won't see it in the launcher until you re-register the kernel.

**The Quick Fix:** Because the kernel spec is ephemeral, you simply need to run
the registration command again in your new container:

```bash
# 1. Activate the persistent env
mamba activate ~/workspace/Temporary/$SCISERVER_USER_NAME/scratch/envs/my-analysis

# 2. Re-register the kernel (if ipykernel is already installed in that env)
python -m ipykernel install --user --name=my-analysis --display-name "My Analysis"
```

**Pro Tip: Create an Alias** To avoid typing this every time, add this alias to
your personal `~/.bashrc` (also saved in your user folders):

```bash
alias link-kernel='python -m ipykernel install --user --name=my-analysis --display-name "Python (My Analysis)"'
```

Now, every time you start a container, just run `link-kernel` after activating
your environment.

---

## Summary of Paths

| Concept | Path | Persistence? |
| :--- | :--- | :--- |
| **Environment Files** | `~/workspace/Storage/$SCISERVER_USER_NAME/persistent/envs/...` | ✅ Yes (Survives restarts) |
| **Mamba Cache (pkgs)** | `~/workspace/Storage/$SCISERVER_USER_NAME/persistent/mamba_cache` | ✅ Yes (Optional, see below) |
| **Kernel Spec** | `~/.local/share/jupyter/kernels/` | ❌ No (Must be re-registered) |

### Optional: Move the Mamba Cache

If you want to speed up future installs, you can also point the package download
cache to persistent storage so you don't re-download tarballs.

```bash
export MAMBA_ROOT_PREFIX=~/workspace/Storage/$SCISERVER_USER_NAME/persistent/mamba_cache
```