# Customizing Your Shell Environment

Every SciServer Compute container comes with a default configuration (aliases,
paths, modules). However, because containers are ephemeral, any changes you make
to `~/.bashrc` inside a running container are lost as soon as you stop it.

To solve this, SciServer automatically sources a **Persistent Bashrc** file from
your User Storage at the end of every login session.

## How it Works

When you open a terminal or launch a JupyterLab session, the container runs the
following logic at the very end of its startup sequence:

```bash
if [ -f $HOME/workspace/Storage/$SCISERVER_USER_NAME/persistent/.bashrc ]; then
    . $HOME/workspace/Storage/$SCISERVER_USER_NAME/persistent/.bashrc
fi
```

**What this means for you:**

1. If you create a file named `.bashrc` inside your persistent storage, it will
   be automatically loaded.
2. Because it runs **last**, it overrides any default aliases or variables set
   by the system.
3. It persists across all containers and images you use.

---

## Step-by-Step Setup

### 1. Create the file

Open a terminal inside a Compute container and create the file using your
preferred editor (or create it via the jupyterlab interface) at this specific
location:

```bash
nvim $HOME/workspace/Storage/$SCISERVER_USER_NAME/persistent/.bashrc
```

### 2. Add your customizations

Here are common examples of what you might want to add.

#### A. Permanent Aliases

Save typing by creating shortcuts for long commands.

```bash
# .bashrc content

# Shortcut to activate your persistent mamba environment
alias myenv='mamba activate ~/workspace/Temporary/$SCISERVER_USER_NAME/scratch/envs/my-analysis'

# Shortcut to print "hello {name}"
alias sayhello='echo "hello $SCISERVER_USER_NAME"'
```

#### B. Environment Variables

Set default paths or API keys.

```bash
# .bashrc content

# Tell Python to look in your persistent storage for modules
export PYTHONPATH="$HOME/workspace/Temporary/$SCISERVER_USER_NAME/scratch/custom_libs:$PYTHONPATH"
```

#### C. Auto-load Mamba Environments

If you want a specific environment to be active *every time* you open a
terminal:

```bash
# .bashrc content
# Activate environment silently
mamba activate ~/workspace/Temporary/$SCISERVER_USER_NAME/scratch/envs/my-analysis 2>/dev/null
```

#### D. Automatic SSH Setup

If you follow the **[Accessing Containers via SSH](./ssh_access)** guide, you
can avoid manually creating the symlink every time you launch a new container by
adding this logic to your persistent `.bashrc`:

```bash
# .bashrc content

# Automatically restore SSH symlink if persistent storage exists
if [ -d "$HOME/workspace/Storage/$SCISERVER_USER_NAME/persistent/.ssh" ]; then
    ln -s "$HOME/workspace/Storage/$SCISERVER_USER_NAME/persistent/.ssh" "$HOME/.ssh" 2>/dev/null
fi
```

### 3. Save and Reload

1. Save the file and exit the editor.
2. To test it immediately without restarting the container, run:

    ```bash
    source $HOME/workspace/Storage/$SCISERVER_USER_NAME/persistent/.bashrc
    ```

3. Verify your aliases work (e.g., type `sayhello`).

---

## Important: Precedence and Conflicts

Because this file is sourced **at the end** of the container's startup, your
settings take precedence over the system defaults.

### Example: Overriding System Aliases

If the system defines:

```bash
alias ls='ls --color=auto'
```

And you add this to your persistent `.bashrc`:

```bash
alias ls='ls -G'
```

**Your version (`ls -G`) will win.**

### Troubleshooting

If your container behaves strangely after adding this file (e.g., commands not
found):

1. Rename the file temporarily to disable it:

    ```bash
    mv $HOME/workspace/Storage/$SCISERVER_USER_NAME/persistent/.bashrc $HOME/workspace/Storage/$SCISERVER_USER_NAME/persistent/.bashrc.bak
    ```

2. Start a new terminal session to confirm the issue is gone.
3. Edit the backup file to fix the syntax, then rename it back to `.bashrc`.

---

## Use Case: Linking to Persistent Environments

This feature works perfectly with the
**[Persistent Environments](./persistent_environments)** guide.

Instead of remembering the full path to your environment every time, add this to
your persistent `.bashrc`:

```bash
# Auto-register your persistent kernel on login
if [ -f ~/workspace/Temporary/$SCISERVER_USER_NAME/scratch/envs/my-analysis/bin/python ]; then
    python -m ipykernel install --user --name=my-analysis --display-name "Python (My Analysis)" 2>/dev/null
    echo "Persistent kernel 'my-analysis' ready."
fi
```

Now, every time you launch a container, your Jupyter kernel is automatically
available.