Apptainer is primarily used through a command-line interface. Typically, you access a Linux machine, like Vista, in a shell (a terminal) and type in commands to start or stop your container and interact with the software in it. The quick start documentation gives an overview of some of the commands, and there is also a full reference section for the command-line interface. If you just want to be reminded of commands that you know exist, you can type apptainer help, which will give you a list of the most commonly used commands.

The command-line interface commands follow the syntax apptainer ... where apptainer is the command that you issue each time. Then Apptainer has subcommands, such as help. There are also command families that have their own subcommands. Each command can have its own set of options, and you may be required to provide arguments. For example, if you are trying to stop a running container, an argument would be the name of that container.

Apptainer on Vista

By default, the Apptainer module is not loaded into the environment. To use Apptainer, you must load the Apptainer module tacc-apptainer.

Running a Container with run

The run command runs a container based on your supplied image, executes its predefined runscript, and exits afterwards. It will run in the foreground, which means that if you type apptainer run <container-image>, your shell or prompt will be occupied while that container is running. Since an image is really a template for creating containers, you can run multiple instances of an image, and later we will see some ways in which you can do that.

In Apptainer, you identify the container image either by the filename for a SIF file, or by the URI for an image in a registry. As we learned in the previous topic, the pull command allows you to download an image from a registry and save it as a SIF file, which can then be used as the image for the run command. If you supply a URI, run will search for an image at that URI, convert it if necessary, place it into the cache (if the image is not already there), and run it without creating a SIF file explicitly.

For example, if we assume that hello-world_latest.sif is a SIF image file in the current working directory, then apptainer run hello-world_latest.sif runs the hello-world container, whose runscript prints out some text. (Note: Cloudflare's hello-world runscript also starts a simple web server, which must be exited with ctrl-C.)

As another example, Docker Hub's default hello-world container can be from its URI, directly. There will be no filename conflict in this case because a separate SIF file is not created. (Note that the text printed by this container is pertinent to Docker, not Apptainer.)

Entering a Container with shell

Instead of issuing the run command, you can use shell to get to the command shell inside the container.

The apptainer shell command starts a container and opens a shell inside it, placing you at the command line inside the container. This is useful for looking around, especially for debugging purposes. If your container isn't doing what you expected, you can inspect the files and configuration to figure out what you need to do differently. The container itself might also be an environment with some software installed, and you can simply issue commands within that shell. To leave the container, type exit.

Executing a Command with exec

A third way to get functionality out of your container is to use exec. The run and exec commands are very similar. The difference is that instead of executing the predefined runscript, exec lets you specify a command to run inside the container. The Apptainer container automatically exits immediately after the command passed to apptainer exec finishes executing (which is unlike Docker).

In this example, running the lolcow container with apptainer run lcow.sif produces a picture of a cow that tells you the current time. This happens because the container's runscript pipes the output of the date command into a program called cowsay. Running the container with apptainer exec lcow.sif cowsay "your message here" executes the cowsay program so that it gives different output. The string you provide as input to cowsay is what the cow says.

You can view the container's runscript with this command: