uenv 8.1 docs (#125)

Author: bcumming

docs/alps/index.md

@@ -19,9 +19,9 @@ Additionally, network segregation ensures secure and isolated communication, wit
 
 -   :fontawesome-solid-signs-post: __Clusters__
 
-    The resources on Alps are partitioned and configured into versatile software defined clusters (vClusters).
+    The resources on Alps are partitioned and configured into versatile software defined clusters.
 
-    [:octicons-arrow-right-24: Alps vClusters][ref-alps-clusters]
+    [:octicons-arrow-right-24: Alps Clusters][ref-alps-clusters]
 
 -   :fontawesome-solid-signs-post: __Hardware__
 

docs/clusters/daint.md

@@ -160,13 +160,7 @@ Daint can also be accessed using [FirecREST][ref-firecrest] at the `https://api.
 
 !!! change "2025-04-30"
     ??? note "uenv is updated from v7.0.1 to v8.1.0"
-        * improved uenv view management
-        * automatic generation of default uenv repository the first time uenv is called
-        * configuration files
-        * bash completion
-        * relative paths can be used for referring to squashfs images
-        * support for `SLURM_UENV` and `SLURM_UENV_VIEW` environment variables (useful for using inside CI/CD pipelines)
-        * better error messages and small bug fixes 
+        [Release notes][ref-uenv-release-notes-v8.1.0]
 
     ??? note "Pyxis is upgraded from v24.5.0 to v24.5.3"
         * Added image caching for Enroot

docs/index.md

@@ -125,7 +125,7 @@ If you cannot find the information that you need in the documentation, help is a
 
     Find out how to use uenv and containers to access software
 
-    [:octicons-arrow-right-24: uenv](software/uenv.md)
+    [:octicons-arrow-right-24: uenv][ref-uenv]
 
     [:octicons-arrow-right-24: Container engine](software/container-engine.md)
 

docs/software/uenv/build.md

@@ -0,0 +1,59 @@
+[](){#ref-uenv-build}
+# Building uenv
+
+## uenv build service
+
+CSCS provides a build service for uenv that takes as its input a uenv recipe, and builds the uenv using the same pipeline used to build the officially supported uenv.
+
+The command takes two arguments:
+
+```
+uenv build <recipe> <label>
+```
+
+* `recipe`: the path to the recipe
+    * A uenv recipe is a description of the software to build in the uenv.
+      See the [stackinator documentation](https://eth-cscs.github.io/stackinator/recipes/) for more information.
+* `label`: the label to attach, of the form `name/version@system%uarch` where:
+    * `name` is the name, e.g. `prgenv-gnu`, `gromacs`, `vistools`.
+    * `version` is a version string, e.g. `24.11`, `v1.2`, `2025-rc2`
+    * `system` is the CSCS cluster to build on (e.g. `daint`, `santis`, `clariden`, `eiger`)
+    * `uarch` is the [micro-architecture][ref-uenv-label-uarch].
+
+!!! example "Building a uenv"
+    The image will be built on `daint` for the `gh200` node type.
+    ```bash
+    uenv build $SCRATCH/recipes/myapp myapp/v3@daint%gh200
+    ```
+
+    The output of the above command will print a url that links to a status page, for you to follow the progress of the build.
+    After a successful build, the uenv can be pulled using an address from the status page:
+
+    ```bash
+    uenv image pull service::myapp/v3:1669479716
+    ```
+
+    Note that the image is given a unique numeric tag, provided on the status page for the build.
+
+!!! info
+    To use an existing uenv recipe as the starting point for a custom recipe, `uenv start` the uenv and take the contents of the `meta/recipe` path in the mounted image (this is the recipe that was used to build the uenv).
+
+All uenv built by `uenv build` are pushed into the `service` namespace, where they **can be accessed by all users logged in to CSCS**.
+This makes it easy to share your uenv with other users, by giving them the name, version and tag of the image.
+
+!!! danger
+    **If, for whatever reason, your uenv can not be made publicly available, do not use the build service.**
+
+!!! example "Search user-built uenv"
+    To view all of the uenv on daint that have been built by the service:
+    ```
+    uenv image find service::@daint
+    ```
+
+## Building with Stackinator
+
+CSCS develops and maintains the [Stackinator](https://eth-cscs.github.io/stackinator) tool that is used to configure and build uenv.
+
+!!! note
+    The tool is currently maintained for internal use, and is used by automated pipelines, including the one used by the `uenv build` command.
+    As such, CSCS provide limited support for the tool.

docs/software/uenv/configure.md

@@ -0,0 +1,60 @@
+[](){#ref-uenv-configure}
+# Configuring uenv
+
+Uenv is designed to work out of the box, with zero configuration for most users.
+There is support for limited per-user configuration via a configuration file, which will be expanded as we add features that make it easier for groups and communities to manage their own environments.
+
+## User configuration
+
+Uenv is configured using a text configuration file.
+
+The location of the configuration file follows the [XDG base directory specification](https://specifications.freedesktop.org/basedir-spec/latest/), with the location defined as follows:
+
+* If the `XDG_CONFIG_HOME` environment variable is set, use `$XDG_CONFIG_HOME/uenv/config`.
+* Otherwise use the default location `$HOME/.config/uenv/config`.
+
+### Syntax
+
+The configuration file uses a simple `key = value` syntax, with comments starting with `#`:
+
+```ini
+# this is a comment
+
+# the following are equivalent
+color = true
+color=true
+```
+
+Notes on the syntax:
+
+* keys are case-sensitive: `color` and `Color` are not equivalent.
+* all keys are lower case
+* white space is trimmed from keys and values, e.g.: `color = true` will be parsed as `key='color'` and `value='true'`.
+
+### Options
+
+| key       | description | default     | values  |
+| ---       | ----------- | --------    | ------  |
+| [`color`][ref-uenv-configure-options-color]   | Use color output  | automatically chosen according to environment | `true`, `false` |
+| [`repo`][ref-uenv-configure-options-repo]    | The default repo location for downloaded uenv images  | `$SCRATCH/.uenv-images`  | An absolute path |
+
+[](){#ref-uenv-configure-options-color}
+#### `color`
+
+By default, uenv will generate color output according to the following:
+
+* if `--no-color` is passed, color output is disabled
+* else if `color` is set in the config file, use that setting
+* else if the `NO_COLOR` environment variable is defined color output is disabled
+* else if the terminal is not TTY disable color
+* else enable color output
+
+[](){#ref-uenv-configure-options-repo}
+#### `repo`
+
+The default repo location for downloaded uenv images.
+The repo is selected according to the following process:
+
+* if the `--repo` CLI arguement overrides 
+* else if `color` is set in the config file, use that setting
+* else use the default value of `$SCRATCH/.uenv-images`

docs/software/uenv/deploy.md

@@ -0,0 +1,235 @@
+[](){#ref-uenv-deploy}
+# Deploying uenv
+
+[](){#ref-uenv-deploy-versions}
+## Versioning and Labeling
+
+Uenv images have a **label** of the following form:
+
+```
+name/version:tag@system%uarch
+```
+
+for example:
+
+```
+prgenv-gnu/24.11:v2@todi%gh200
+```
+
+### uenv name
+
+The name of the uenv. In this case `prgenv-gnu`.
+
+### uenv version
+
+The version of the uenv.
+
+The format of `version` depends on the specific uenv.
+Often they use the `yy.mm` format, though they may also use the version of the software being packaged.
+For example the [`namd/3.0`][ref-uenv-namd] uenv packages version 3.0 of the popular [NAMD](https://www.ks.uiuc.edu/Research/namd/) simulation tool.
+
+### uenv tag
+
+Used to differentiate between _releases_ of a versioned uenv.
+Some examples of tags include:
+
+* `rc1`, `rc2`: release candidates;
+* `v1`: a first release typically made after some release candidates;
+* `v2`: a second release, that fixes issues in `v1`
+
+### uenv system
+
+The name of the [Alps cluster][ref-alps-clusters] for which the uenv was built.
+
+[](){#ref-uenv-label-uarch}
+### uenv uarch
+
+The node type (microarchitecture) that the uenv is built for.
+
+| uarch                      | CPU | GPU | comment |
+| ----- | --- | --- | ------ |
+|[gh200][ref-alps-gh200-node]| 4 72-core NVIDIA Grace (`aarch64`) | 4 NVIDIA H100 GPUs | |
+|[zen2][ref-alps-zen2-node]  | 2 64-core AMD Rome (`zen2`)        | - | used in Eiger|
+|[a100][ref-alps-a100-node]  | 1 64-core AMD Milan (`zen3`)       | 4 NVIDIA A100 GPUs | |
+|[mi200][ref-alps-mi200-node]| 1 64-core AMD Milan (`zen3`)       | 4 AMD Mi250x GPUs  | |
+|[mi300][ref-alps-mi300-node]| 4 24-core AMD Genoa (`zen4`)       | 4 AMD Mi300 GPUs  | |
+| zen3                       | 2 64-core AMD Milan (`zen3`)       | - | only in MCH system |
+
+## Registries
+
+The following naming scheme is employed in the OCI container artifactory for uenv images:
+
+```text
+namespace/system/uarch/name/version:tag
+```
+
+Where the fields `system`, `uarch`, `name`, `version` and `tag` are defined above.
+
+The `namespace` is one of:
+
+* `build`: where the CI/CD pipeline pushes uenv images.
+* `deploy`: where uenv images are copied by CSCS staff when they are officially provided to users.
+* `service`: where the uenv [build service][ref-uenv-build] pushes images.
+
+!!! info "JFrog uenv registry"
+    The OCI container registry used to host uenv is on JFrog, and can be browsed at [jfrog.svc.cscs.ch/artifactory/uenv/](https://jfrog.svc.cscs.ch/artifactory/uenv/) (you may have to log in with CSCS credentials from the a VPN/CSCS network).
+
+    The address of individual uenv images is of the form
+    ```
+    https://jfrog.svc.cscs.ch/uenv/namespace/system/uarch/name/version:tag
+    ```
+    For example:
+    ```
+    https://jfrog.svc.cscs.ch/uenv/deploy/eiger/zen2/cp2k:2024.1
+    ```
+
+## uenv recipes and definitions
+
+The uenv recipes are maintained in a public GitHub repository: [eth-cscs/alps-uenv](https://github.com/eth-cscs/alps-uenv).
+
+The recipes for each uenv version are stored in the `recipes` subdirectory. 
+Specific uenv recipes are stored in `recipes/name/version/uarch/`.
+
+The `cluster` is specified when building and deploying the uenv, while the `tag` is specified when deploying the uenv.
+
+## uenv Deployment
+
+### Deployment Rules
+
+A recipe can be built for deployment on different vClusters, and for multiple targets.
+For example:
+
+* A multicore recipe could be built for `zen2` or `zen3` nodes
+* A GROMACS recipe that is tuned for A100 GPUs can be built and deployed on any vCluster supporting the A100 architecture
+
+However, it is not desirable to build every recipe on every possible target system.
+For example:
+
+* An ICON development environment would only be deployed on the weather and climate platform
+* A GROMACS recipe would not be deployed on the weather and climate platrofm
+* Development builds only need to run on test and staging clusters
+
+A YAML file `config.yaml` is maintained in the [github.com/eth-cscs/alps-uenv](https://github.com/eth-cscs/alps-uenv/blob/main/config.yaml) repository that maps
+recipes to deployed versions on mucroarchitectures.
+
+### Permissions
+
+!!! note "For CSCS staff"
+    This information applies only to CSCS staff.
+
+Deployment and deletion of uenv requires elevated permissions.
+Before you can modify the uenv registry, you need to set up credentials.
+
+* Your CSCS username needs to be added to the `uenv-admin` group on JFrog, and
+* you need to generate a new token for the [JFrog](https://jfrog.svc.cscs.ch) registry.
+
+Once you have the token, you can save it in a file.
+
+!!! danger
+
+    Save the token file somwhere safe, for example in `~/.ssh/jfrog-token`.
+
+
+The token file can be passed to the `uenv` command line tool using the `--token` option.
+
+```bash
+uenv image copy --token=${HOME}/.ssh/jfrog-token <SOURCE> <DESTINATION>
+```
+
+### Deploying a uenv
+
+!!! note "For CSCS staff"
+    This information applies only to CSCS staff.
+
+The CI/CD pipeline for [eth-cscs/alps-uenv](https://github.com/eth-cscs/alps-uenv) pushes images to the JFrog uenv registry in the `build::` namespace.
+
+Deploying a uenv copies the uenv image from the `build::` namespace to the `deploy::` namespace. The Squashfs image itself is not copied;
+a new tag for the uenv is created in the `deploy::` namespace.
+
+The deployment is performed using the `uenv` command line tool, as demonstrated below:
+
+```bash
+uenv image copy build::<SOURCE> deploy::<DESTINATION> # (1)!
+```
+
+1. `<DESTINATION>` must be fully qualified.
+
+!!! example "Deploy Using Image ID"
+    
+    Deploy a uenv from `build::` using the ID of the image:
+
+    ```bash
+    uenv image copy build::d2afc254383cef20 deploy::prgenv-nvfortran/24.11:v1@daint%gh200
+    ```
+
+!!! example "Deploy Using Qualified Name"
+
+    Deploy a uenv using the qualified name:
+
+    ```
+    uenv image copy build::quantumespresso/v7.4:1653244229 deploy::quantumespresso/v7.4:v1@daint%gh200
+    ```
+
+    !!! note 
+
+        The build image uses the CI/CD pipeline ID as the tag. You will need to choose an appropriate tag.
+
+!!! example "Deploy a uenv from One vCluster to Another"
+
+    You can also deploy a uenv from one vCluster to another.
+    For example, if the `uenv` for `prgenv-gnu` has been deployed on `daint`,
+    to make it available on `santis`, you can use the following command:
+
+    ```bash
+    uenv image copy deploy::prgenv-gnu/24.11:v1@daint%gh200 deploy::prgenv-gny/24.11@santis%gh200
+    ```
+
+### Removing a uenv
+
+To remove a uenv, you can use the `uenv` command line tool:
+
+```bash
+uenv image delete --token=${HOME}/.ssh/jfrog-token deploy::<IMAGE>
+```
+
+!!! danger
+
+    Removing a uenv is disruptive.
+    Please have a look at out [uenv removal policy][ref-uenv-removal] for more information.
+
+## Source code access
+
+Some source artifacts are stored in JFrog, including:
+
+* source code for software that can't be downloaded directly from the internet directly;
+* and tar balls for custom software.
+
+These artifacts are stored in a JFrog "generic repository" [uenv-sources].
+
+Each software package has a sub-directory and all image paths are lower case (e.g. `uenv-sources/namd`).
+
+By default, all packages in [uenv-sources]  are anonymous read access
+to enable users to build uenv on vClusters without configuring access tokens.
+However,
+
+* access to some packages is restricted by applying access rules to the package path
+* e.g. access to `uenv-sources/vasp` is restricted to members of the vasp6 group
+
+Permissons to acces restricted resources is set on a per-pipeline basis
+
+* For example, only the `alps-uenv` pipeline has access to the VASP source code, while the [`uenv build`][ref-uenv-build] pipeline does not.
+
+| Package | Access | Path | Notes | Contact |
+|---------|--------|------|-------| ------- |
+| `cray-mpich` | anonymous | `uenv-sources/cray-mpich` | `cray-mpich`, `cray-gtl`, `cray-pals`, `cray-mpi` | Simon Pintarelli, Benjamin Comming|
+| `namd` | `uenv-sources-csstaff` | `uenv-sources/namd` | NAMD requires an account to download the source code | Rocco Meli |
+| `vasp` | `vasp6`, `cscs-uenv-admin` | `uenv-sources/vasp` | VASP requires a paid license to access source | Simon Frasch |
+| `vmd` | `uenv-sources-csstaff` | `uenv-sources/vmd` | VMD requires an account to download the source code | Alberto Invernizzi |
+
+[](){#ref-uenv-removal}
+## Deprecation and removal of uenv
+
+!!! todo "Finalise and document the deprecation process"
+
+
+[uenv-sources]: https://jfrog.svc.cscs.ch/artifactory/uenv-sources/