Update conda-store explanations

docusaurus-docs/conda-store/explanations/artifacts.md

@@ -4,26 +4,24 @@ description: Understand environment artifacts generated by conda-store
 
 # Artifacts
 
-:::warning
-This page is in active development, some content may be inaccurate.
-:::
-
 conda environments can be created in a few different ways.
-conda-store creates "artifacts" (corresponding to different environment creation options) that can be shared with colleagues and can be used to reproduce environments.
-In the conda-store UI, these are available in the "Logs and Artifacts" section at the end of the environment page.
+conda-store creates "artifacts" (corresponding to different environment creation options) for every environment, that can be shared with colleagues and used to reproduce environments.
+In the conda-store UI, these are available in the **"Logs and Artifacts"** section
+at the end of the environment page.
 
 The following sections describe the various artifacts generated and how to create environments with them.
 
-### YAML file (pinned)
+:::note
+Environments in shared namespaces can be accessed by everyone with access to that namespace, in which case you may not need to share the artifacts manually.
+:::
 
-YAML files that follow the conda specification is a common way to create environments.
-conda-store creates a "pinned" YAML, where all the exact versions of requested packages (including `pip` packages) as well as all their dependencies are specified, to ensure new environments created match the original environment as closely as possible.
+## YAML file (pinned)
 
-A pinned YAML file is generated for each environment ta is built.
-This includes pinning of the `pip`` packages as well.
+YAML file that follows the conda specification is a common way to create environments.
+conda-store creates a "pinned" YAML, where all the exact versions of requested packages (including `pip` packages) as well as all their dependencies are specified, to ensure new environments created match the original environment as closely as possible.
 
 :::info
-In rare cases, the completely pinned packages may not solve because packages are
+In rare cases, the pinned packages may not solve because packages are
 routinely marked as broken and removed.
 
 **conda-forge** (default channel in conda-store)
@@ -32,159 +30,173 @@ broken][conda-forge-immutability-policy].
 Most other channels do not have such a policy.
 :::
 
-Assuming you have `conda` installed, to create a conda environment (on any machine) using this file:
+Click on **"Show yml file"** link in the conda-store UI to open the file in a new browser tab. You can download the file[^1] and share with someone or use it to create an environment on a different machine.
+
+[^1]: Concretely, download the browser page displaying the file. For example, on macOS: Right-click on the page -> Select "Save As" -> Give the file a meaningful name (like `environment.yml`).
+
+Assuming `conda` is installed, run the following CLI command with the corresponding filename to create a conda environment (on any machine):
 
-1. Click on **"Show yml file"** link in the conda-store UI to open the file in a new browser tab.
-2. Save the file with: Right-click on the page -> Select "Save As" -> Give the file a meaningful name (like `environment.yml`)
-3. Run the following command and use the corresponding filename:
-   ```bash
-   conda env create --file <environment.yml>
-   ```
+```bash
+conda env create --file <environment.yml>
+```
 
-### Lockfile
+## Lockfile
 
-A conda lockfile is a representation of only the `conda` dependencies in
+A conda lockfile is a representation of all (`conda` and `pip`) dependencies in
 a given environment.
-conda-store created lockfiles using the [conda-lock][conda-lock-github] project.
+conda-store creates lockfiles using the [conda-lock][conda-lock-github] project.
 
-:::warning
-This file will not reproduce the `pip` dependencies in a given environment.
-It is usually a good practice to not mix pip and conda dependencies.
-:::
+Click on **"Show lockfile"** to open the lockfile in a new browser tab.
+You can download the file[^1] and share with someone or use it to create an environment in a different space.
 
-Click the `lockfile` icon to download the
-lockfile. First install `conda-lock` if it is not already installed.
+At the new location, install `conda-lock` if it is not already installed:
 
 ```shell
-conda install -c conda-forge lockfile
+conda install -c conda-forge conda-lock
 ```
 
-Install the locked environment file from conda-store.
+Create an environment using the lockfile generated by conda-store:
 
 ```shell
-conda-lock install <lockfile-filename>
+conda-lock install <lockfile.yml>
 ```
 
-### conda-pack archive
+## Tarballs or archives
 
-[Conda-Pack](https://conda.github.io/conda-pack/) is a package for
-creating tarballs of given Conda environments. Creating a Conda archive
-is not as simple as packing and unpacking a given directory. This is
-due to the base path for the environment that may
-change. [Conda-Pack](https://conda.github.io/conda-pack/) handles all
-of these issues. Click the `archive` button and download the given
-environment. The size of the archive will be less than the size seen
-on the environment UI element due to compression.
+:::warning
+Environment builds from archives is only supported on Linux machines
+because the tarballs are built on Linux machines.
+:::
 
-```shell
-conda install -c conda-forge conda-pack
+A tarball or archive is a _packaged_ environment that can be moved, unpacked, and used in a different location or on a different machine.
+
+conda-store uses [Conda-Pack][conda-pack], a library for
+creating tarballs of conda environments.
+
+:::tip
+Creating an archive of a conda environment is more complex than packing and unpacking a given directory because the base path for the environment can change.
+[Conda-Pack][conda-pack] handles this complexity.
+:::
+
+Click **"Download archive"** button to download the archive of your conda environment, and share/move it to the desired location.
+
+To install the tarball, execute the following commands at the location:
+
+1. Create a new directory for the environment (called `<my_env>` here) and unpack the environment tarball in that directory:
+
+```bash
+mkdir -p <my_env>
+tar -xzf <my_env_tarball_file.tar.gz> -C <my_env>
 ```
 
-Install the Conda-Pack tarball. The directions are [slightly
-complex](https://conda.github.io/conda-pack/#commandline-usage). Note
-that `my_env` can be any name in any given prefix.
+2. Activate the environment with:
 
-```shell
-mkdir -p my_env
-tar -xzf <conda-pack-tarfile>.tar.gz -C my_env
+```bash
+source <my_env>/bin/activate
+```
 
-source my_env/bin/activate
+3. From the active environment, clean-up prefixes:
 
+```bash
 conda-unpack
 ```
 
-### Docker images
+4. You can use any library present in the environment, and when done, deactivate the environment with:
 
-:::note
+```bash
+source <my_env>/bin/deactivate
+```
+
+Learn more about using environment tarballs in the [conda-pack documentation][conda-pack-usage].
+
+## Docker images
+
+:::warning
 Docker image creation is currently only supported on Linux.
+
+The docker image generation and registry features are experimental,
+and the following instructions are not thoroughly tested.
+If you face any difficulties, open an issue on the GitHub repository.
 :::
 
-conda-store acts as a docker registry which allows for interesting
-ways to handle Conda environment. In addition this registry leverages
-[conda-docker](https://github.com/conda-incubator/conda-docker) which
-builds docker images without docker allowing for advanced caching,
-reduced image sizes, and does not require elevated privileges. Click
-on the `docker` link this will copy a url to your clipboard. Note the
-beginning of the url for example `localhost:8080/`. This is required to tell
-docker where the docker registry is located. Otherwise by default it
-will try and user docker hub. Your url will likely be different.
-
-The `conda-store` docker registry requires authentication via any
-username with password set to a token that is generated by visiting
-the user page to generate a token. Alternatively in the
-`conda_store_config.py` you can set
-`c.AuthenticationBackend.predefined_tokens` which have environment
-read permissions on the given docker images needed for pulling.
+conda-store acts as a docker registry.
+It leverages [Conda Docker][conda-docker], which builds docker images without Docker, allowing for advanced caching, reduced image sizes, and does not require elevated privileges.
 
-```
-docker login -u token -p <conda-store-token>
-docker pull <docker-url>
-docker run -it <docker-url> python
-```
+### Authentication
 
-#### General usage
+The `conda-store` docker registry requires authentication.
+You can use **any username** and your **user token as the password**.
 
-```shell
-docker run -it localhost:8080/<namespace>/<environment-name>
+```bash
+docker login -u <any-username> -p <conda-store-token>
 ```
 
-If you want to use a specific build (say one that was built in the
-past and is not the current environment) you can visit the specific
-build that you want in the UI and copy its docker registry tag
-name. The tag name is a combination of `<specification-sha256>-<build
-date>-<build id>-<environment name>` that we will refer to as build
-key. An example would be
-`localhost:5000/filesystem/python-numpy-env:583dd55140491c6b4cfa46e36c203e10280fe7e180190aa28c13f6fc35702f8f-20210825-180211-244815-3-python-numpy-env`.
+To get your user token:
 
-```shell
-docker run -it localhost:8080/<namespace>/<environment-name>:<build_key>
+1. Visit your user page at `<your-conda-store-domain>/admin/user`
+2. Click on "Create token", which displays your token
+3. Click on "copy" to copy the token to your clipboard
+
+Alternatively, you can set `c.AuthenticationBackend.predefined_tokens` in `conda_store_config.py`, which have environment read permissions on the given docker images required for pulling images.
+
+### General usage
+
+To use a specific environment build, click on the **"Show Docker image"** to get the URL to the docker image. For example: `localhost:8080/analyst/python-numpy-env:583dd55140491c6b4cfa46e36c203e10280fe7e180190aa28c13f6fc35702f8f-20210825-180211-244815-3-python-numpy-env`.
+
+The URL consists of: `<conda-store-domain>/<namespace>/<environment-name>:<build_key>`
+
+* The conda-store domain (for example `localhost:8080/`) at the beginning tells Docker where the docker registry is located. Otherwise, Docker will try to use Docker Hub by default.
+* The `<namespace>/<environment-name>` refers to the specific conda environment
+* The "build key" is a combination of `<specification-sha256>-<build
+date>-<build id>-<environment name>` which points to specific build of the environment. For example, a past version of the environment.
+
+To use a conda-store environment docker image:
+
+```bash
+docker run -it <docker-url>
 ```
 
-#### On Demand Docker Image
+### On-demand (dynamic) docker image
 
-conda-store has an additional feature which allow for specifying the
-packages within the docker image name itself without requiring an
-actual environment to be created on the conda-store UI side.
+In conda-store, you can also specify the required packages within the docker image name itself, without needing an actual environment to be created by conda-store UI.
 
-The following convention is used
-`<registry-url>:<registry-port>/conda-store-dynamic/`. After
-`conda-store-dynamic` you specify packages needed separated by
-slashes. Additionally you may specify package constraints
-for example `<=1.10` as `.lt.1.10`.
+The URL format is: `<registry-url>:<registry-port>/conda-store-dynamic/<package-constraint-1>/.../<package-constraint-n>`.
 
-As full example support we want python less than `3.8` and NumPy
-greater than `1.0`. This would be the following docker image
-name. `<registry-url>:<registry-port>/conda-store-dynamic/python.lt.3.8/numpy.gt.1.0`. conda-store
-will then create the following environment and the docker image will
-download upon the docker image being built.
+After `conda-store-dynamic`, you can specify packages with constraints separated by
+slashes in the following format:
+* `<=1.10` as `.lt.1.10`
+* `>=1.10` as `.gt.1.10`
 
-### Installers
+For example, if you need Python less than `3.10` and NumPy
+greater than `1.0`, this would be the docker image
+name: `<registry-url>:<registry-port>/conda-store-dynamic/python.lt.3.10/numpy.gt.1.0`.
 
-conda-store uses [constructor] to generate an installer for the current platform
-(where the server is running):
+conda-store creates the environment ands builds the docker image, which you can then download.
 
-- on Linux and macOS, it generates a `.sh` installer
-- on Windows, it generates a `.exe` installer using NSIS.
+## Installers
+
+Installers are another way to share and use a set of (bundled) packages.
+conda-store uses [constructor][constructor-docs] to generate an installer for the current platform (where the server is running):
+
+- on Linux and MacOS, it generates a `.sh` installer
+- on Windows, it generates a `.exe` installer using NSIS
 
 conda-store automatically adds `conda` and `pip` to the target environment
 because these are required for the installer to work.
 
-Also note that `constructor` uses a separate dependency solver instead of
+:::note
+`constructor` uses a separate dependency solver instead of
 utilizing the generated lockfile, so the package versions used by the installer
 might be different compared to the environment available in conda-store. There
 are plans to address this issue in the future.
-
-#### Existing Deployments
-
-conda-store saves environment settings and doesn't automatically update them on
-startup (see `CondaStore.ensure_settings`). Existing deployments need to
-manually enable installer builds via the admin interface. This can be done by
-going to `<CondaStoreServer.url_prefix>/admin/setting/<namespace>/<env>/` (or
-clicking on the `Settings` button on the environment page) and adding
-`"CONSTRUCTOR_INSTALLER"` to `build_artifacts`.
+:::
 
 <!-- External links -->
 [conda-docs]: https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/environments.html
 [conda-forge-immutability-policy]: https://conda-forge.org/docs/maintainer/updating_pkgs.html#packages-on-conda-forge-are-immutable
 [conda-lock-github]: https://github.com/conda-incubator/conda-lock
 [constructor]: https://github.com/conda/constructor
+[conda-pack]: https://conda.github.io/conda-pack/
+[conda-pack-usage]: https://conda.github.io/conda-pack/index.html#commandline-usage
+[conda-docker]: https://github.com/conda-incubator/conda-docker
+[constructor-docs]: https://conda.github.io/constructor/