diff --git a/docs/guides/terminal.md b/docs/guides/terminal.md index 92660933..6fede42e 100644 --- a/docs/guides/terminal.md +++ b/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 `` 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. + diff --git a/docs/software/uenv/index.md b/docs/software/uenv/index.md index 1307af3f..0f31b60b 100644 --- a/docs/software/uenv/index.md +++ b/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.