finish release notes; deploy guide; configure guide

bcumming · bcumming · commit 843b50eddf29 · 2025-06-02T18:30:27.000+02:00
diff --git a/docs/alps/index.md b/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__
 
diff --git a/docs/clusters/daint.md b/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
diff --git a/docs/software/uenv/configure.md b/docs/software/uenv/configure.md
@@ -2,22 +2,22 @@
 # 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.
 
-### Location of the configuration file
-
 The location of the configuration file follows the [XDG base directory specification](https://specifications.freedesktop.org/basedir-spec/latest/).
+
 * If the `XDG_CONFIG_HOME` environment variable is set, the `$XDG_CONFIG_HOME/uenv/config`.
 * Otherwise it defaults to `$HOME/.config/uenv/config`.
 
 ### Syntax
 
-A custom, but simple `key = value` syntax with comments marked with `#`
+The configuration file uses a simple `key = value` syntax, with comments starting with `#`:
 
-```
+```ini
 # this is a comment
 
 # the following are equivalent
@@ -35,21 +35,25 @@ Notes on the syntax:
 
 | key       | description | default     | values  |
 | ---       | ----------- | --------    | ------  |
-| `color`   | Use color output  | automatically chosen according to TTY | `true`, `false` |
-| `repo`    | The default repo location for downloaded uenv images  | `$SCRATCH/.uenv-images`  | An absolute path |
+| [`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 location of
+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
diff --git a/docs/software/uenv/deploy.md b/docs/software/uenv/deploy.md
@@ -4,9 +4,7 @@
 [](){#ref-uenv-deploy-versions}
 ## Versioning and Labeling
 
-Uenv images have a _label_ of the following form:
-
-Uenv are referred to using **labels**, where a label has the following form
+Uenv images have a **label** of the following form:
 
 ```
 name/version:tag@system%uarch
@@ -74,6 +72,18 @@ The `namespace` is one of:
 * `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 at [jfrog.svc.cscs.ch/artifactory/uenv/](https://jfrog.svc.cscs.ch/artifactory/uenv/).
+
+    The address used to refer uenv images is of the form
+    ```
+    https://jfrog.svc.cscs.ch/uenv/namespace/system/uarch/name/version:release
+    ```
+    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).
@@ -88,25 +98,26 @@ The `cluster` is specified when building and deploying the uenv, while the `rele
 ### Deployment Rules
 
 A recipe can be built for deployment on different vClusters, and for multiple targets.
+For example:
 
-??? 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
+* 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:
 
-??? 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
+* 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 [eth-cscs/alps-uenv](https://github.com/eth-cscs/alps-uenv) repository that maps
+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/deletion requires elevated permissions.
 Before you can modify the uenv registry, you need to set up credentials.
 
@@ -128,6 +139,9 @@ 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 imagre from the `build::` namespace to the `deploy::` namespace. The Squashfs image itself is not copied;
@@ -146,7 +160,7 @@ uenv image copy build::<SOURCE> deploy::<DESTINATION> # (1)!
     Deploy a uenv from `build::` using the ID of the image:
 
     ```bash
-    uenv image copy build::d2afc254383cef20 deploy::prgenv-nvfortran/24.11:v1
+    uenv image copy build::d2afc254383cef20 deploy::prgenv-nvfortran/24.11:v1@daint%gh200
     ```
 
 !!! example "Deploy Using Qualified Name"
@@ -176,32 +190,35 @@ uenv image copy build::<SOURCE> deploy::<DESTINATION> # (1)!
 To remove a uenv, you can use the `uenv` command line tool:
 
 ```bash
-uenv image remove --token=${HOME}/.ssh/jfrog-token deploy::<IMAGE>
+uenv image delete --token=${HOME}/.ssh/jfrog-token deploy::<IMAGE>
 ```
 
 !!! warning
 
-    Removing a uenv is disruptive. Please have a look at out [uenv removal policy][ref-uenv-removal] for more information.
+    Removing a uenv is disruptive.
+    Please have a look at out [uenv removal policy][ref-uenv-removal] for more information.
 
-## uenv Sources
+## Source code access
 
-Some source artifacts are stored in JFrog:
+Some source artifacts are stored in JFrog, including:
 
-* sorce code for software that can't be downloaded directly from the internet directly,
-* tar balls for custom software.
+* 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-resources/namd`).
+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
+* 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
 
-A CI/CD job has access to all of [iuenv-sources] resources.
+* 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 |
 |---------|--------|------|-------| ------- |
@@ -211,8 +228,9 @@ A CI/CD job has access to all of [iuenv-sources] resources.
 | `vmd` | `uenv-sources-csstaff` | `uenv-sources/vmd` | VMD requires an account to download the source code | Alberto Invernizzi |
 
 [](){#ref-uenv-removal}
-## uenv deprecation and removal
+## Deprecation and removal of uenv
+
+!!! todo "Finalise and document the deprecation process"
 
-!!! todo
 
 [uenv-sources]: https://jfrog.svc.cscs.ch/artifactory/uenv-sources/
diff --git a/docs/software/uenv/index.md b/docs/software/uenv/index.md
@@ -13,24 +13,30 @@ Each environment contains a software stack, comprised of compilers, libraries, t
 
 <div class="grid cards" markdown>
 
--   :fontawesome-solid-layer-group: __Configuring uenv__
+-   :fontawesome-solid-layer-group: __Building uenv__
 
-    !!! todo
+    More adventurous users can create their own uenv for personal use, and for other users in their team and community.
 
-    [:octicons-arrow-right-24: Configuring uenv][ref-uenv-configure]
+    [:octicons-arrow-right-24: Building uenv][ref-uenv-build]
 
--   :fontawesome-solid-layer-group: __Building uenv__
+-   :fontawesome-solid-layer-group: __Configuring uenv__
 
-    !!! todo
+    Users can customize the behavior of uenv using a configuration file.
 
-    [:octicons-arrow-right-24: Building uenv][ref-uenv-build]
+    [:octicons-arrow-right-24: Configuring uenv][ref-uenv-configure]
 
 -   :fontawesome-solid-layer-group: __Deploying uenv__
 
-    !!! todo
+    Documentation on how CSCS deploys uenv images, that might also be of interest to users.
 
     [:octicons-arrow-right-24: Deploying uenv][ref-uenv-deploy]
 
+-   :fontawesome-solid-layer-group: __Release notes__
+
+    Release notes for the uenv tools (CLI and Slurm plugin).
+
+    [:octicons-arrow-right-24: Deploying uenv][ref-uenv-release-notes]
+
 </div>
 
 ## Before starting
diff --git a/docs/software/uenv/release-notes.md b/docs/software/uenv/release-notes.md
@@ -0,0 +1,25 @@
+[](){#ref-uenv-release-notes}
+# uenv releases notes
+
+The version of uenv deployed on the main [Alps clusters][ref-alps-clusters] is **v8.1.0**.
+
+[](){#ref-uenv-release-notes-v8.1.0}
+## v8.1.0
+
+This version replaced v7.1.0 on Alps clusters.
+
+### features
+
+* improved uenv view management
+* automatic generation of default uenv repository the first time uenv is called
+    * this fixes the error message
+* bash completion
+* support for configuration files
+    * currently only support setting `color` and default uenv repo
+* support for `SLURM_UENV` and `SLURM_UENV_VIEW` environment variables for use inside CI/CD pipelines.
+
+### small fixes
+
+* better error messages and small bug fixes
+* relative paths can be used for referring to squashfs images
+
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -85,6 +85,7 @@ nav:
       - 'Configuration': software/uenv/configure.md
       - 'Building uenv': software/uenv/build.md
       - 'Deploying uenv': software/uenv/deploy.md
+      - 'Release notes': software/uenv/release-notes.md
     - 'Container Engine': software/container-engine.md
     - 'Unsupported Software': software/unsupported.md
   - 'Services':
