add a guide for creating custom uenv environments (#206)

In response to https://jira.cscs.ch/browse/SD-66316

https://docs.tds.cscs.ch/206/software/uenv/#custom-environments

---------

Co-authored-by: Rocco Meli <[email protected]>

Author: bcumming

docs/guides/terminal.md

@@ -76,3 +76,49 @@ export PATH=$xdgbase/bin:$PATH
 !!! note "XDG what?"
     The [XDG base directory specification](https://specifications.freedesktop.org/basedir-spec/latest/) is used by most applications to determine where to look for configurations, and where to store data and temporary files.
 
+[](){#ref-guides-terminal-bashrc}
+## Modifying bashrc
+
+The `~/.bashrc` in your home directory is executed __every time__ you log in, and there is no way to log in without executing it.
+
+It is strongly recommended that customization in `~/.bashrc` should be kept to the bare minimum:
+
+1. It sets a fixed set of environment options every time you log in, and all downstream scripts and Slurm batch jobs might assume that these commands have run, so that later modifications to `~/.bashrc` can break workflows in ways that are difficult to debug.
+    * If a script or batch job requires environment modifications, implement them there.
+    * In other words, move the definition of environment used by a workflow to the workflow definition.
+1. It makes it difficult for CSCS to provide support, because it is difficult for support staff to reproduce your environment, and it can take a lot of back and forth before we determine that the root cause of an issue is a command in `~/.bashrc`.
+
+
+!!! warning "Do not call `module` in bashrc"
+    Calls to `module use` and `module load` in `~/.bashrc` is possible, however avoid it for the reasons above.
+    If there are module commands in your `~/.bashrc`, remember to provide a full copy of `~/.bashrc` with support tickets.
+
+!!! danger "Do not call `uenv` in bashrc"
+    The `uenv` command is designed for creating isolated environments, and calling it in `~/.bashrc` will not work as expected.
+    See the [uenv docs][ref-uenv-customenv] for more information about how to create bespoke uenv environments that can be started with a single command.
+
+??? note "Help, I broke bashrc!"
+    It is possible to add commands to bashrc that will stop you from being able to log in.
+    The author of these docs has done it more than once, after ignoring their own advice.
+
+    For example, if the command `exit` is added to `~/.bashrc` you will be logged out every time you log in.
+
+    The first thing to try is to execute a command that will back up `~/.bashrc`, and remove `~/.bashrc`:
+    ```bash
+    ssh eiger.cscs.ch 'bash --norc --noprofile -c "mv ~/.bashrc ~/.bashrc.back"'
+    ```
+    If this works, you can then log in normally, and edit the backup and copy it back to `~/.bashrc`.
+
+    If there is a critical error, like calling `exit`, the approach above won't work.
+    In such cases, the only solution that doesn't require root permissions is to log in and hit `<ctrl-c>` during the log in.
+    With luck, this will cancel the login process before `~/.bashrc` is executed, and you will be able to edit and fix `~/.bashrc`.
+    Note that you might have to try a few times to get the timing right.
+
+    If this does not work, create a [service desk ticket][ref-get-in-touch] with the following message:
+
+    !!! example "Help request"
+        My bashrc has been modified, and I can't log in any longer to `insert-system-name`.
+        My username is `insert-cscs-username`.
+        Can you please make a backup copy of my bashrc, i.e. `mv ~/.bashrc ~/.bashrc.back`,
+        so that I can log in and fix the issue.
+

docs/software/uenv/index.md

@@ -601,3 +601,66 @@ uenv image find @'*'%gh200
 
 !!! note
     The wild card `*` used for "all systems" must always be escaped in single quotes: `@'*'`.
+
+[](){#ref-uenv-customenv}
+## Custom environments
+
+!!! warning "[Keep bashrc clean][ref-guides-terminal-bashrc]"
+
+It is common practice to add `module` commands to `~.bashrc`, for example
+```bash title="~/.bashrc"
+# make my custom modules available
+module use $STORE/myenv/modules
+# load the modules that I always want in the environment
+module load ncview
+```
+
+This will make custom modules available, and load `ncview`, every time you log in.
+It is not possible to do the equivalent with `uenv start`, for example:
+```bash title="~/.bashrc"
+# start the uenv that I always use
+uenv start prgenv-gnu/24.11:v2 --view=default
+# ERROR: the following lines will not be executed
+module use $STORE/myenv/modules
+module load ncview
+```
+
+!!! question "Why can't I use `uenv start` in `~/.bashrc`?"
+    The `module` command uses some "clever" tricks to modify the environment variables in your current shell.
+    For example, `module load ncview` will modify the value of environment variables like `PATH`, `LD_LIBRARY_PATH`, and `PKG_CONFIG_PATH`.
+
+    The `uenv start` command loads a uenv, and __starts a new shell__, ready for you to enter commands.
+    This means that lines in the `.bashrc` that follow the command are never executed.
+
+    Things are further complicated because if `uenv start` is executed inside `~/.bashrc`, the shell is not a tty shell.
+
+It is possible to create a custom command that will start a new shell with a uenv loaded, with additional customizations to the environment (e.g. loading modules and setting environment variables).
+
+The first step is to create a script that performs the the customization steps to perform once the uenv has been loaded.
+Here is an example for an environment called `myenv`:
+
+```bash title="~/.myenvrc"
+# always add this line
+source ~/.bashrc
+
+# then add customization commands here
+module use $STORE/myenv/modules
+module load ncview
+export DATAPATH=$STORE/2025/data
+```
+
+Then create an alias in `~/.bashrc` for the `myenv` environment:
+
+```bash title="~/.bashrc"
+alias myenv='uenv run prgenv-gnu/24.11:v2 --view=default -- bash --rcfile ~/.myenvrc'
+```
+
+This alias uses `uenv run` to start a new bash shell that will apply the customizations in `~/.myenvrc` once the uenv has been loaded.
+Then, the environment can be started with a single command once logged in.
+
+```console
+$ ssh eiger.cscs.ch
+$ myenv
+```
+
+The benefit of this approach is that you can create multiple environments, whereas modifying `.bashrc` will lock you into using the same environment every time you log in.