@@ -52,23 +72,45 @@ More information is provided in the [CHTC Recipes Repository](https://github.com
+
+
----
+We recommend using Apptainer as a first choice because you can build the container
+on our servers and it has some features that allow it to be used on a greater variety
+of computing nodes.
+
+However, there are many good reasons to use Docker (or Apptainer) depending on your
+circumstances. Here is a list of things to consider when deciding which path to take.
-## Containers
+* If your software has an existing Docker or Apptainer/Singularity implementation, use that.
+* If you or your group have an existing Docker container, use Docker.
+* If you already know how to use Docker or Apptainer/Singularity, use whichever you are familiar with.
+* If you want to create a container that can run both on CHTC and your own computer, use Docker.
+* If you want to create a container that you and collaborators can use on your own computers and CHTC, use Docker.
+* If you want to keep your container more private, use Apptainer.
-Many of the recipes in our Recipes repository involve building your own container.
-In this section, we provide a brief introduction into how to use containers for setting up your own software to run on the High Throughput system.
+In certain cases, it is reasonable to use a non-container option for software installation, especially when using a package manager like `conda`.
-### What is a Container?
+If you are not sure what to choose, talk to the facilitation team! That's why we're here.
+
+
+## Container overview
+
+In this section, we provide a brief introduction into what containers are,
+why we recommend them, and a big picture view of how to use them on our High Throughput system.
+
+### What is a container?
*"A container is a standard unit of software that packages up code and all its dependencies so the application runs quickly and reliably from one computing environment to another."*
-- [Docker](https://www.docker.com/resources/what-container/)
@@ -95,7 +137,58 @@ While there are some caveats, containers are useful for deploying software on sh
> When we talk about building or moving or distributing a container, we're actually talking about the file(s) that constitute the container.
> When a container is "running" or "executed", the container image is used to create the run time environment for executing the programs installed inside of it.
-### Container Technologies
+### Why use containers?
+
+We recognize that learning about containers is its own challenge! However, we have found
+in the long run, that containers provide the best long-term user experience when running
+jobs in CHTC, including:
+
+- a consistent environment no matter what computer your job runs on
+- a consistent environment with stable software versions (good for reproducibility)
+- ability to fully customize the software installation
+
+Our goal is to make finding or building your container as easy as possible, so you
+can have most of these benefits, without too much pain.
+
+### Using containers on CHTC
+
+If you have a container, adding it to your job is easy! It's just one more line
+in the submit file. The challenge is usually getting a container that has what you need.
+There are typically two ways of doing so:
+
+1. Find an existing container
+1. Build your own container image
+
+If building your own container, the process will include:
+
+1. Writing a build file, called either a `Dockerfile` or definition (`.def`) file.
+ * Consult your software's documentation
+ * Choose an existing base container
+ * Add the details needed for your software
+ * Leverage CHTC's [recipes repository](https://github.com/CHTC/recipes)
+1. (If using Apptainer: starting an interactive session on a CHTC build server)
+1. Running a command to "build" the container image, using your build file as the
+template for doing so
+1. Running a command to put the container in a location where you can use it in your jobs.
+
+These guides talk about how to do the above steps for either Apptainer or Docker.
+- [Use Custom Software in Jobs Using Apptainer](apptainer-htc)
+- [Use Custom Software in Jobs Using Docker](docker-jobs)
+
+> A common question is whether the software installation process is repeated each time a container is used.
+> The answer is "no".
+> The software installation process only occurs when the container is actually being built.
+> Once the container has been built, no changes can be made to the container when being used (on CHTC systems).
+
+### Container build recipes
+
+If you need to create your own build file, CHTC provides many specific examples
+in our "Recipes" repository on Github:
+[https://github.com/CHTC/recipes](https://github.com/CHTC/recipes).
+
+Links to specific recipes are used in the [Software](#software) section for certain softwares and coding languages.
+
+### Container technologies
There are two container technologies supported by CHTC: [Docker](https://www.docker.com/) and [Apptainer](https://apptainer.org/).
Here we briefly discuss the advantages of each.
@@ -126,118 +219,10 @@ On the HTC system, you can provide the name of your Apptainer file in your submi
and HTCondor will use a copy of it to create the software environment for executing your job.
You can use Apptainer to build the container image file on CHTC servers, so there is no need to install the container software on your own computer.
-### Use an Existing Container
-
-If you or a colleague have already built a container for use on CHTC, it is fairly straightforward to modify your jobs to use the container environment as discussed below.
-#### Use a Docker container
-*Full Guide*: [Running HTC Jobs Using Docker Containers](docker-jobs.html)
+## Related Pages
-If the container you want to use is hosted on Docker Hub, find the container "address" and provide it in your submit file.
-The address typically has the convention of `user/repository:tag`, though official repositories such as Python are just `repository:tag`.
-In your submit file, use
-
-```
-container_image = docker://user/repository:tag
-```
-{:.sub}
-
-If the container you want to use is hosted in a different container registry, there should still be a container "address" to use,
-but now there will be a website prefix.
-
-```
-container_image = docker://registry_address/user/repository:tag
-```
-{:.sub}
-
-For example, to use a container from the [NVIDIA Container Registry](https://catalog.ngc.nvidia.com/containers) (`nvcr`),
-you would have `docker://nvcr.io/nvidia/repository:tag`.
-
-[Back to Top](#top)
-
-#### Use an Apptainer container
-
-*Full Guide*: [Use Apptainer Containers](apptainer-htc.html)
-
-For historical reasons, the Apptainer container file has the file extension `.sif`.
-The syntax for giving HTCondor the name of the container file depends on where it is located on the CHTC system.
-
-If the `.sif` file is in a **`/home` directory**:
-
-```
-container_image = path/to/my-container.sif
-```
-{:.sub}
-
-If the `.sif` file is in a **`/staging` directory**:
-
-```
-container_image = file:///staging/path/to/my-container.sif
-```
-{:.sub}
-
-If the `.sif` file is **in a `/staging` directory AND you are using `want_campus_pools` or `want_ospool`**:
-
-```
-container_image = osdf:///chtc/staging/path/to/my-container.sif
-```
-{:.sub}
-
-[Back to Top](#top)
-
-### Build Your Own Container
-
-You can build your own container with the operating system and software that you want to use.
-The general process is the same whether you are using Docker or Apptainer.
-
-1. **Consult your software's documentation**
-
- Determine the requirements for installing the software you want to use.
- In particular you are looking for (a) the operating systems it is compatible with and (b) the prerequisite libraries or packages.
-
-2. **Choose a base container**
-
- The base container should at minimum use an operating system compatible with your software.
- Ideally the container you choose also has many of the prerequisite libraries/programs already installed.
-
-3. **Create your own definition file**
-
- The definition file contains the installation commands needed to set up your software.
- (The structure of the container "definition" file differs between Docker and Apptainer, but it is fairly straightforward to translate between the two.)
-
-4. **Build the container**
-
- Once the definition file has been written, you must "build" the container.
- The computer you use to build the container will run through the installation commands, almost as if you were actually installing the software on that computer,
- but will save the results into the container file(s) for later use.
-
-5. **Distribute the container**
-
- To use the container on CHTC servers, you'll need to distribute the container to right location.
- For Docker containers, this means "pushing" the container to Docker Hub or similar container registry.
- For Apptainer containers, this typically means copying the container `.sif` file to the [/staging system](file-avail-largedata.html).
-
-You can then use the container following the [instructions above](#use-an-existing-container).
-
-> A common question is whether the software installation process is repeated each time a container is used.
-> The answer is "no".
-> The software installation process only occurs when the container is actually being built.
-> Once the container has been built, no changes can be made to the container when being used (on CHTC systems).
-
-#### Build your own Docker container
-
-Please follow the instructions in our guide [Build a Docker Container Image](docker-build.html) to build your own container using Docker.
-As mentioned above, you will need to have Docker installed on your own computer.
-This is so that you can push the completed container to Docker Hub.
-
-*You are unable to push containers from CHTC to Docker Hub, so please do not build Docker containers using CHTC!*
-
-#### Build your own Apptainer container
-
-Please follow the instructions in our guide [Use Apptainer Containers](apptainer-htc.html) to build your own container using Apptainer.
-You can use CHTC servers to build the container, so there is no need to install any software on your computer.
-
-[Back to Top](#top)
-
----
+- [Use Custom Software in Jobs Using Apptainer](apptainer-htc)
+- [Use Custom Software in Jobs Using Docker](docker-jobs)
+- [Using Apptainer Containers on HPC](apptainer-hpc.html)