You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
If an EDF is located in the [EDF search path][ref-ce-edf-search-path], `--environment` also accepts the EDF filename without the `.toml` extension:
103
-
104
-
!!! example "Specifying EDF in the default search path"
105
-
```bash
106
-
$ srun --environment=debian cat /etc/os-release
107
-
PRETTY_NAME="Debian GNU/Linux 12 (bookworm)"
108
-
NAME="Debian GNU/Linux"
109
-
VERSION_ID="12"
110
-
...
111
-
```
112
-
113
-
### Use from batch scripts
114
-
115
-
The recommended approach is to use `--environment` as part of the Slurm command (e.g., `srun` or `salloc`):
116
-
117
-
!!! example "Adding `--environment` to `srun`"
118
-
```bash
119
-
#!/bin/bash
120
-
#SBATCH --job-name=edf-example
121
-
...
122
-
123
-
# Run job step
124
-
srun --environment=debian cat /etc/os-release
125
-
```
126
-
127
-
Alternatively, the `--environment` option can also be specified with an `#SBATCH` option.
128
-
However, the support status is still **experimental** and may result in unexpected behaviors.
129
-
130
-
!!! note
131
-
Specifying `--environment` with `#SBATCH` will put the entire batch script inside the containerized environment, requiring the Slurm hook to use any Slurm commands within the batch script (e.g., `srun` or `scontrol`).
132
-
The hook is controlled by the `ENROOT_SLURM_HOOK` environment variable and activated by default on most vClusters.
133
-
134
-
[](){#ref-ce-edf-search-path}
135
-
### EDF search path
136
-
137
-
By default, the EDFs for each user are looked up in `$HOME/.edf`.
138
-
The default EDF search path can be changed through the `EDF_PATH` environment variable.
139
-
`EDF_PATH` must be a colon-separated list of absolute paths to directories, where the CE searches each directory in order.
140
-
If an EDF is located in the search path, its name can be used in the `--environment` option without the `.toml` extension.
141
-
142
-
!!! example "Using `EDF_PATH` to control the default search path"
By default, images defined in the EDF as remote registry references (e.g. a Docker reference) are automatically pulled and locally cached.
164
-
A cached image would be preferred to pulling the image again in later usage.
165
-
166
-
An image cache is automatically created at `.edf_imagestore` in the user's scratch folder (i.e., `${SCRATCH}/.edf_imagestore`), under which cached images are stored with the corresponding CPU architecture suffix (e.g., `x86` and `aarch64`).
167
-
Cached images may be subject to the automatic cleaning policy of the scratch folder.
168
-
169
-
Should users want to re-pull a cached image, they have to remove the corresponding image in the cache.
170
-
171
-
To choose an alternative image store path (e.g., to use a directory owned by a group and not to an individual user), users can specify an image cache path explicitly by defining the environment variable `EDF_IMAGESTORE`.
172
-
`EDF_IMAGESTORE` must be an absolute path to an existing folder.
173
-
174
-
!!! note
175
-
If the CE cannot create a directory for the image cache, it operates in cache-free mode, meaning that it pulls an ephemeral image before every container launch and discards it upon termination.
176
-
177
-
### Pulling images manually
178
-
179
-
To work with images stored from the NGC Catalog, please refer also to the next section "Using images from third party registries and private repositories".
180
-
181
-
To bypass any caching behavior, users can manually pull an image and directly plug it into their EDF.
182
-
To do so, users may execute `enroot import docker://[REGISTRY#]IMAGE[:TAG]` to pull container images from OCI registries to the current directory.
183
-
184
-
After the import is complete, images are available in Squashfs format in the current directory and can be used in EDFs:
185
-
186
-
!!! example "Manually pulling an `nvidia/cuda:11.8.0-cudnn8-devel-ubuntu22.04` image"
1. Assuming `example.toml` is already written at `${HOME}/.edf`.
204
-
205
-
!!! note
206
-
It is recommended to save images in `/capstor/scratch/cscs/${USER}` or its subdirectories before using them with the CE.
207
-
208
-
[](){#ref-ce-third-party-private-registries}
209
-
### Third-party and private registries
210
-
211
-
[Docker Hub](https://hub.docker.com/) is the default registry from which remote images are imported.
212
-
213
-
!!! warning "Registry rate limits"
214
-
Some registries will rate limit image pulls by IP address.
215
-
Since [public IPs are a shared resource][ref-guides-internet-access] we recommend authenticating even for publicly available images.
216
-
For example, [Docker Hub applies its rate limits per user when authenticated](https://docs.docker.com/docker-hub/usage/).
217
-
218
-
To use an image from a different registry, the corresponding registry URL has to be prepended to the image reference, using a hash character (#) as a separator:
219
-
220
-
!!! example "Using a third-party registry within an EDF"
To import images from private repositories, access credentials should be configured by individual users in the `$HOME/.config/enroot/.credentials` file, following the [netrc file format](https://everything.curl.dev/usingcurl/netrc).
234
-
Using the `enroot import` documentation page as a reference:
235
-
236
-
??? example "`netrc` example"
237
-
```bash
238
-
# NVIDIA NGC catalog (both endpoints are required)
0 commit comments