# Shell Automation (`.bashrc`)

The "Automation Engine" for your SciServer container is a persistent `.bashrc`
file. While containers have a default system configuration, any changes you make
to the local `~/.bashrc` are lost on restart.

To solve this, SciServer has been configured to automatically source a specific
**persistent** `.bashrc` file from your User Storage on any new session.

## How it Works

When you open a terminal or launch a JupyterLab session, the container runs this
logic automatically:

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

**Key Implications:**

1. **Automatic Loading:** If you create this file in your persistent storage, it
   loads every time.
2. **Precedence:** Because it runs **last**, it overrides any default system
   aliases or variables.
3. **Cross-Container:** It persists across different images and container
   restarts.

---

## Setting Up Your Automation Engine

### 1. Create the file

Create the file at the specific persistent location:

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

### 2. Add Your Customizations

Here are sample uses for your persistent `.bashrc`.

#### A. Persistent Aliases

Save typing for long commands:

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

# print "hello <username>" every time a new terminal is opened
alias sayhello='echo "hello $SCISERVER_USER_NAME"'
```

#### B. Environment Variables

Set default paths or API keys:

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

#### C. Automation Recipes

As seen in the [Persistent Python Environments](./python_environments.md) and
[Persistent SSH and Terminal configs](./identity_access.md) guides, you can use
this file to automatically register kernels or link SSH keys.

---

## Testing and Troubleshooting

### Apply Changes Immediately

To test changes without restarting the container, run:

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

### Troubleshooting Errors

If your terminal starts behaving strangely (e.g., commands not found) after
editing this file:

1. **Disable it temporarily:**

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

2. **Restart your terminal.**
3. **Fix the syntax error** in the `.bak` file and rename it back.