Alliance Doc

Apptainer: Difference between revisions

Page Discussion

Apptainer (view source)

Revision as of 18:33, 4 January 2023

2,057 bytes removed ,  1 year ago
→‎Running Programs Within a Container
Line 121: Line 121:
* <code>your-container-name.sif</code> is the name of your container
* <code>your-container-name.sif</code> is the name of your container


===Running Software: <code>apptainer run</code>===
===Running Software===


====<code>apptainer run</code> or <code>apptainer exec</code>====
The <code>apptainer run</code> command will launch an Apptainer container, runs the <code>%runscript</code> defined for that container (if one is defined), and then runs the specific command (subject to the code in the <code>%runscript</code> script).  
The <code>apptainer run</code> command will launch an Apptainer container, runs the <code>%runscript</code> defined for that container (if one is defined), and then runs the specific command (subject to the code in the <code>%runscript</code> script).  


* '''NOTE:''' Using this command is preferred over using the <code>apptainer exec</code> command (which directly runs a command within the specified container).
* '''NOTE:''' Using <code>apptainer run</code> command is preferred over using the <code>apptainer exec</code> command (which directly runs a command within the specified container).


For example, suppose you want to run the <code>g++</code> compiler inside your container to compile a C++ program called <code>myprog.cpp</code> and then run that program. To this this you might use this command:
For example, suppose you want to run the <code>g++</code> compiler inside your container to compile a C++ program called <code>myprog.cpp</code> and then run that program. To this this you might use this command:
Line 149: Line 150:
as well as the [http://apptainer.org/docs/user/main/index.html official Apptainer documentation].
as well as the [http://apptainer.org/docs/user/main/index.html official Apptainer documentation].


===Interactively Running Software: <code>apptainer shell</code>===
====Interactively Running Software: <code>apptainer shell</code>====


The <code>apptainer run</code>, <code>apptainer exec</code>, and <code>apptainer instance</code> commands run the programs provided and return after execution which makes them excellent for such and for use in BASH scripts and SLURM job scripts. That said, there are times when one needs to interactively do work inside a container. To run commands interactively while remaining inside a container, one uses the <code>apptainer shell</code> command.
The <code>apptainer run</code>, <code>apptainer exec</code>, and <code>apptainer instance</code> commands run the programs provided immediately which makes them excellent for use in BASH and SLURM job scripts. There are times when one needs to interactively do work inside a container. To run commands interactively while remaining inside a container, use the <code>apptainer shell</code> command instead.


For example, to run commands interactively in a container one first invokes the <code>apptainer shell</code> command, e.g.,
For example, to run commands interactively in a container one first invokes the <code>apptainer shell</code> command, e.g.,
Line 176: Line 177:
'''IMPORTANT:''' In addition to choose to use the above options, if you are making use of a persistent overlay image (as a separate file or contained within the SIF file) and want changes to be written to that image, it is extremely important to pass the <code>-w</code> or <code>--writable</code> option to your container. If this option is not passed to it, any changes you make to the image in the <code>apptainer shell</code> session will not be saved!
'''IMPORTANT:''' In addition to choose to use the above options, if you are making use of a persistent overlay image (as a separate file or contained within the SIF file) and want changes to be written to that image, it is extremely important to pass the <code>-w</code> or <code>--writable</code> option to your container. If this option is not passed to it, any changes you make to the image in the <code>apptainer shell</code> session will not be saved!


===Running Software (Basic): <code>apptainer exec</code>===
====Running Daemons: <code>apptainer instance</code>====
 
The <code>apptainer exec</code> command will launch an Apptainer container and directly run the command specified. Prefer using <code>apptainer run</code> command instead of using this command as <code>apptainer run</code> will run the container's <code>%runscript</code> which may be important for establishing the correct execution environment for the software in your container.
 
The use of the <code>apptainer exec</code> is identical to <code>apptainer run</code> except <code>exec</code> is specified instead of <code>run</code>. For example, suppose you want to run the <code>g++</code> compiler inside your container to compile a C++ program called <code>myprog.cpp</code> and then run that command. This command might be used:
 
apptainer exec your-container-name.sif g++ -O2 -march=broadwell ./myprog.cpp
apptainer exec your-container-name.sif ./a.out
 
where:
* <code>your-container-name.sif</code> is the name of your SIF file
* <code>g++ -O2 -march=broadwell ./myprog.cpp</code> is the command you want to run inside the container
 
On our clusters, you will want to use a number of additional options (that appear after <code>run</code> and before <code>your-container-name.sif</code>). These options will include <code>-C</code>, <code>-c</code>, <code>-e</code>, <code>-W</code> as well as various bind mount options to make your disk space available to the programs that run in your container. For example:
 
  apptainer exec -C -W $SLURM_TMPDIR -B /home -B /project -B /scratch your-container-name.sif g++ -O2 -march=broadwell ./myprog.cpp
  apptainer exec -C -W $SLURM_TMPDIR -B /home -B /project -B /scratch your-container-name.sif ./a.out
 
For more information on these options see the following sections on this page:
 
* [[#Important_Command_Line_Options|Important Command Line Options]]
* [[#Using_GPUs|Using GPUs]]
* [[#Bind_Mounts_and_Persistent_Overlays|Bind Mounts and Persistent Overlays]]
 
as well as the [http://apptainer.org/docs/user/main/index.html official Apptainer documentation].
 
===Running Daemons: <code>apptainer instance</code>===


Apptainer has been designed to be able to properly run daemons within compute jobs on clusters. Running daemons is achieved, in part, by using <code>apptainer instance</code>. See the [http://apptainer.org/docs/user/main/running_services.html official Apptainer documentation on Running Services] for the details.
Apptainer has been designed to be able to properly run daemons within compute jobs on clusters. Running daemons is achieved, in part, by using <code>apptainer instance</code>. See the [http://apptainer.org/docs/user/main/running_services.html official Apptainer documentation on Running Services] for the details.
Preney
cc_staff
156

edits

Retrieved from "https://docs.alliancecan.ca/wiki/Special:MobileDiff/126010"