forked from apptainer/singularity-userdocs
-
Notifications
You must be signed in to change notification settings - Fork 0
/
user-guide.tex.bak
4481 lines (3274 loc) · 236 KB
/
user-guide.tex.bak
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
\documentclass[a4paper]{article}
\usepackage{titlesec}
\usepackage{hyperref}
\usepackage{caption}
\titleclass{\subsubsubsection}{straight}[\subsection]
\newcounter{subsubsubsection}[subsubsection]
\renewcommand\thesubsubsubsection{\thesubsubsection.\arabic{subsubsubsection}}
\renewcommand\theparagraph{\thesubsubsubsection.\arabic{paragraph}} % optional; useful if paragraphs are to be numbered
\titleformat{\subsubsubsection}
{\normalfont\normalsize\bfseries}{\thesubsubsubsection}{1em}{}
\titlespacing*{\subsubsubsection}
{0pt}{3.25ex plus 1ex minus .2ex}{1.5ex plus .2ex}
\makeatletter
\renewcommand\paragraph{\@startsection{paragraph}{5}{\z@}%
{3.25ex \@plus1ex \@minus.2ex}%
{-1em}%
{\normalfont\normalsize\bfseries}}
\renewcommand\subparagraph{\@startsection{subparagraph}{6}{\parindent}%
{3.25ex \@plus1ex \@minus .2ex}%
{-1em}%
{\normalfont\normalsize\bfseries}}
\def\toclevel@subsubsubsection{4}
\def\toclevel@paragraph{5}
\def\toclevel@paragraph{6}
\def\l@subsubsubsection{\@dottedtocline{4}{7em}{4em}}
\def\l@paragraph{\@dottedtocline{5}{10em}{5em}}
\def\l@subparagraph{\@dottedtocline{6}{14em}{6em}}
\makeatother
\setcounter{secnumdepth}{5}
\setcounter{tocdepth}{5}
\usepackage[document]{ragged2e}
\usepackage{blindtext}
\usepackage{enumitem}
\usepackage{xcolor}
\usepackage{graphicx}
\usepackage{float}
\usepackage{listings} % Include the listings-package
\usepackage{color}
\definecolor{mygreen}{rgb}{0,0.6,0}
\definecolor{mygray}{rgb}{0.5,0.5,0.5}
\definecolor{mymauve}{rgb}{0.58,0,0.82}
\lstset{
backgroundcolor=\color{white}, % choose the background color; you must add \usepackage{color} or \usepackage{xcolor}; should come as last argument
basicstyle=\footnotesize, % the size of the fonts that are used for the code
breakatwhitespace=false, % sets if automatic breaks should only happen at whitespace
breaklines=true, % sets automatic line breaking
captionpos=b, % sets the caption-position to bottom
commentstyle=\color{mygreen}, % comment style
deletekeywords={...}, % if you want to delete keywords from the given language
escapeinside={\%*}{*)}, % if you want to add LaTeX within your code
extendedchars=true, % lets you use non-ASCII characters; for 8-bits encodings only, does not work with UTF-8
frame=single, % adds a frame around the code
keepspaces=true, % keeps spaces in text, useful for keeping indentation of code (possibly needs columns=flexible)
keywordstyle=\color{blue}, % keyword style
language=Octave, % the language of the code
morekeywords={*,...}, % if you want to add more keywords to the set
numbers=left, % where to put the line-numbers; possible values are (none, left, right)
numbersep=5pt, % how far the line-numbers are from the code
numberstyle=\tiny\color{mygray}, % the style that is used for the line-numbers
rulecolor=\color{black}, % if not set, the frame-color may be changed on line-breaks within not-black text (e.g. comments (green here))
showspaces=false, % show spaces everywhere adding particular underscores; it overrides 'showstringspaces'
showstringspaces=false, % underline spaces within strings only
showtabs=false, % show tabs within strings adding particular underscores
stepnumber=2, % the step between two line-numbers. If it's 1, each line will be numbered
stringstyle=\color{mymauve}, % string literal style
tabsize=2, % sets default tabsize to 2 spaces
title=\lstname % show the filename of files included with \lstinputlisting; also try caption instead of title
}
\usepackage{lipsum}
\usepackage{setspace} % for \onehalfspacing and \singlespacing macros
\newcommand{\itab}[1]{\hspace{0em}\rlap{#1}}
\newcommand{\tab}[1]{\hspace{.2\textwidth}\rlap{#1}}
\onehalfspacing
\usepackage{etoolbox}
\AtBeginEnvironment{quote}{\singlespacing\small}
\usepackage[a4paper, total={7in, 8in}]{geometry}
%\geometry{legalpaper, margin=0.8in}
\date{\vspace{-5ex}}
\makeatletter
\def\@seccntformat#1{%
\expandafter\ifx\csname c@#1\endcsname\c@section
Section \thesection:
\else
\csname the#1\endcsname\quad
\fi}
\makeatother
\usepackage{hyperref}
\hypersetup{
colorlinks=true,
linkcolor=black,
filecolor=magenta,
urlcolor=cyan,
}
\renewcommand{\thesection}{\arabic{section}.}
\renewcommand{\thesubsection}{\arabic{section}.\arabic{subsection}}
\makeatletter
\def\@seccntformat#1{\@ifundefined{#1@cntformat}%
{\csname the#1\endcsname\quad}% default
{\csname #1@cntformat\endcsname}}% enable individual control
\makeatother
\begin{document}
\begin{figure}
\centering
%\includegraphics[width=0.5,height=0.5]{logo.png}
\includegraphics{logo.png}
\caption{Singularity}
\end{figure}
\justify
\section{Getting Started}
\subsection{Quick Start}
\label{sec:quickstart}
This guide is intended for running Singularity on a computer where you have root (administrative) privileges. If you are learning about Singularity on a system where you lack root privileges, you can still complete the steps that do not require the sudo command. If you need to request an installation on your shared resource, check out our requesting an installation help page for information to send to your system administrator.
\newpage
\tableofcontents
\newpage
\subsubsection{Installation}
There are many ways to \hyperref[sec:installation]{{\textcolor{cyan}{install Singularity}}} but this quick start guide will only cover one.
\\[0.1in]
\lstset{language=bash} % Set your language (you can change the language for each code-block optionally)
\lstset{basicstyle = \ttfamily,columns=fullflexible}
\begin{lstlisting}[frame=single]
git clone https://github.com/singularityware/singularity.git
cd singularity
./autogen.sh
./configure --prefix=/usr/local
make
sudo make install
\end{lstlisting}
Singularity must be installed as root to function properly.
\subsubsection{Overview of the Singularity Interface}
Singularity’s \hyperref[sec:commandlineinterface]{{\textcolor{cyan}{command line interface}}} allows you to build and interact with containers transparently. You can run programs inside a container as if they were running on your host system. You can easily redirect IO, use pipes, pass arguments, and access files, sockets, and ports on the host system from within a container.\\
The \colorbox{lightgray}{-{}-help} option gives an overview of Singularity options and subcommands as follows:
\begin{lstlisting}[frame=single]
$ singularity --help
USAGE: singularity [global options...] <command> [command options...] ...
GLOBAL OPTIONS:
-d|--debug Print debugging information
-h|--help Display usage summary
-s|--silent Only print errors
-q|--quiet Suppress all normal output
--version Show application version
-v|--verbose Increase verbosity +1
-x|--sh-debug Print shell wrapper debugging information
GENERAL COMMANDS:
help Show additional help for a command or container
selftest Run some self tests for singularity install
CONTAINER USAGE COMMANDS:
exec Execute a command within container
run Launch a runscript within container
shell Run a Bourne shell within container
test Launch a testscript within container
CONTAINER MANAGEMENT COMMANDS:
apps List available apps within a container
bootstrap *Deprecated* use build instead
build Build a new Singularity container
check Perform container lint checks
inspect Display a container's metadata
mount Mount a Singularity container image
pull Pull a Singularity/Docker container to $PWD
COMMAND GROUPS:
image Container image command group
instance Persistent instance command group
CONTAINER USAGE OPTIONS:
see singularity help <command>
For any additional help or support visit the Singularity
website: http://singularity.lbl.gov/
\end{lstlisting}
For any additional help or support visit the Singularity
website: \href{https://www.sylabs.io/}{https://www.sylabs.io/}\\
Singularity uses positional syntax. Global options follow the \colorbox{lightgray}{singularity} invocation and affect the way that Singularity runs any command. Then commands are passed followed by their options.\\
For example, to pass the \colorbox{lightgray}{-{}-debug} option to the main \colorbox{lightgray}{singularity} command and run Singularity with debugging messages on:\\
\begin{lstlisting}[frame=single]
$ singularity --debug run shub://GodloveD/lolcow
\end{lstlisting}
And to pass the \colorbox{lightgray}{-{}-containall} option to the \colorbox{lightgray}{run} command and run a Singularity image in an isolated manner:
\begin{lstlisting}[frame=single]
$ singularity run --containall shub://GodloveD/lolcow
\end{lstlisting}
To learn more about a specific Singularity command, type one of the following:
\begin{lstlisting}[frame=single]
$ singularity help <command>
$ singularity --help <command>
$ singularity -h <command>
$ singularity <command> --help
$ singularity <command> -h
\end{lstlisting}
Users can also \hyperref[sec:writehelpdocs]{{\textcolor{cyan}{write help docs specific to a container}}} or for an internal module called an \hyperref[sec:scifapps]{{\textcolor{cyan}{app}}}. If those help docs exist for a particular container, you can view them like so.\\[0.1in]
\begin{lstlisting}[frame=single]
$ singularity help container.simg # See the container's help, if provided
$ singularity help --app foo container.simg # See the help for foo, if provided
\end{lstlisting}
\subsubsection{Download pre-built images}
You can use the \hyperref[sec:pull]{{\textcolor{cyan}{pull}}} and \hyperref[sec:build]{{\textcolor{cyan}{build}}} commands to download pre-built images from an external resource like \href{https://singularity-hub.org/}{Singularity Hub} or \href{https://hub.docker.com/}{Docker Hub}. When called on a native Singularity images like those provided on Singularity Hub, \colorbox{lightgray}{pull} simply downloads the image file to your system.
\begin{lstlisting}[frame=single]
$ singularity pull shub://vsoch/hello-world # pull with default name, vsoch-hello-world-master.simg
$ singularity pull --name hello.simg shub://vsoch/hello-world # pull with custom name
\end{lstlisting}
Singularity images can also be pulled and named by an associated GitHub commit or content hash.\\
You can also use \colorbox{lightgray}{pull} with the \colorbox{lightgray}{docker://} uri to reference Docker images served from a registry. In this case \colorbox{lightgray}{pull} does not just download an image file. Docker images are stored in layers, so \colorbox{lightgray}{pull} must also combine those layers into a usable Singularity file.
\begin{lstlisting}[frame=single]
$ singularity pull docker://godlovedc/lolcow # with default name
$ singularity pull --name funny.simg docker://godlovedc/lolcow # with custom name
\end{lstlisting}
Pulling Docker images reduces reproducibility. If you were to pull a Docker image today and then wait six months and pull again, you are not guaranteed to get the same image. If any of the source layers has changed the image will be altered. If reproducibility is a priority for you, try building your images from Singularity Hub.\\
You can also use the \colorbox{lightgray}{build} command to download pre-built images from an external resource. When using \colorbox{lightgray}{build} you must specify a name for your container like so:
\begin{lstlisting}[frame=single]
$ singularity build hello-world.simg shub://vsoch/hello-world
$ singularity build lolcow.simg docker://godlovedc/lolcow
\end{lstlisting}
Unlike \colorbox{lightgray}{pull}, \colorbox{lightgray}{build} will convert your image to the latest Singularity image format after downloading it.
\colorbox{lightgray}{build} is like a “Swiss Army knife” for container creation. In addition to downloading images, you can use \colorbox{lightgray}{build} to create images from other images or from scratch using a \hyperref[sec:recipefile]{{\textcolor{cyan}{recipe file}}}. You can also use \colorbox{lightgray}{build} to convert an image between the 3 major container formats supported by Singularity. We discuss those image formats below in the \hyperref[sec:buildimagesfromscratch]{{\textcolor{cyan}{Build images from scratch}}} section.
\subsubsection{Interact with images}
Once you have an image, you can interact with it in several ways. For these examples we will use a \colorbox{lightgray}{hello-world.simg} image that can be downloaded from Singularity Hub like so.
\begin{lstlisting}[frame=single]
$ singularity pull --name hello-world.simg shub://vsoch/hello-world
\end{lstlisting}
\subsubsubsection{Shell}
The \hyperref[sec:shell]{{\textcolor{cyan}{shell}}} command allows you to spawn a new shell within your container and interact with it as though it were a small virtual machine.
\begin{lstlisting}[frame=single]
$ singularity shell hello-world.simg
Singularity: Invoking an interactive shell within container...
# I am the same user inside as outside!
Singularity hello-world.simg:~/Desktop> whoami
vanessa
Singularity hello-world.simg:~/Desktop> id
uid=1000(vanessa) gid=1000(vanessa) groups=1000(vanessa),4(adm),24,27,30(tape),46,113,128,999(input)
\end{lstlisting}
\colorbox{lightgray}{shell} also works with the \colorbox{lightgray}{shub://} and \colorbox{lightgray}{docker://} URIs. This creates an ephemeral container that disappears when the shell is exited.
\begin{lstlisting}[frame=single]
$ singularity shell shub://vsoch/hello-world
\end{lstlisting}
\subsubsubsection{Executing Commands}
The \hyperref[sec:exec]{{\textcolor{cyan}{exec}}} command allows you to execute a custom command within a container by specifying the image file. For instance, to list the root (/) of our hello-world.simg image, we could do the following:\
\begin{lstlisting}[frame=single]
$ singularity exec hello-world.simg ls /
anaconda-post.log etc lib64 mnt root singularity tmp
bin home lost+found opt run srv usr
dev lib media proc sbin sys var
\end{lstlisting}
\colorbox{lightgray}{exec} also works with the \colorbox{lightgray}{shub://} and \colorbox{lightgray}{docker://} URIs. This creates an ephemeral container that executes a command and disappears.\\
\begin{lstlisting}[frame=single]
$ singularity exec shub://singularityhub/ubuntu cat /etc/os-release
\end{lstlisting}
\subsubsubsection{Running a container}
Singularity containers contain “\hyperref[sec:runscript]{{\textcolor{cyan}{runscripts}}}”. These are user defined scripts that define the actions a container should perform when someone runs it. The runscript can be triggered with the run command, or simply by calling the container as though it were an executable.
\begin{lstlisting}[frame=single]
$ singularity run hello-world.simg
$ ./hello-world.simg
\end{lstlisting}
\colorbox{lightgray}{run} also works with \colorbox{lightgray}{shub://} and \colorbox{lightgray}{docker://} URIs. This creates an ephemeral container that runs and then disappears.
\begin{lstlisting}[frame=single]
$ singularity run shub://GodloveD/lolcow
\end{lstlisting}
\subsubsubsection{Working with Files}
Files on the host are reachable from within the container.\\[0.1in]
\begin{lstlisting}[frame=single]
$ echo "Hello World" > $HOME/hello-kitty.txt
$ singularity exec vsoch-hello-world-master.simg cat $HOME/hello-kitty.txt
Hello World
\end{lstlisting}
This example works because \colorbox{lightgray}{hello-kitty.txt} exists in the user’s home directory. By default singularity bind mounts \colorbox{lightgray}{/home/\$USER}, \colorbox{lightgray}{/tmp}, and \colorbox{lightgray}{\$PWD} into your container at runtime.\\
You can specify additional directories to bind mount into your container with the \colorbox{lightgray}{\hyperref[sec:bindpaths]{{\textcolor{cyan}{-{}-bind}}}} option. In this example, the \colorbox{lightgray}{data} directory on the host system is bind mounted to the \colorbox{lightgray}{/mnt} directory inside the container.\\
\begin{lstlisting}[frame=single]
$ echo "I am your father" >/data/vader.sez
$ ~/sing-dev/bin/singularity exec --bind /data:/mnt hello-world.simg cat /mnt/vader.sez
I am your father
\end{lstlisting}
\subsubsection{Build images from scratch}
\label{sec:buildimagesfromscratch}
As of Singularity v2.4 by default \colorbox{lightgray}{build} produces immutable images in the squashfs file format. This ensures reproducible and verifiable images.\\
However, during testing and debugging you may want an image format that is writable. This way you can \colorbox{lightgray}{shell} into the image and install software and dependencies until you are satisfied that your container will fulfill your needs. For these scenarios, Singularity supports two other image formats: a \colorbox{lightgray}{sandbox} format (which is really just a chroot directory), and a \colorbox{lightgray}{writable} format (the ext3 file system that was used in Singularity versions less than 2.4).
For more details about the different build options and best practices, read about the \hyperref[sec:singularityflow]{{\textcolor{cyan}{singularity flow}}}.
\subsubsubsection{Sandbox Directory}
To build into a \colorbox{lightgray}{sandbox} (container in a directory) use the \colorbox{lightgray}{build --sandbox} command and option:\\
\begin{lstlisting}[frame=single]
$ sudo singularity build --sandbox ubuntu/ docker://ubuntu
\end{lstlisting}
This command creates a directory called \colorbox{lightgray}{ubuntu/} with an entire Ubuntu Operating System and some Singularity metadata in your current working directory.\\
You can use commands like \colorbox{lightgray}{shell}, \colorbox{lightgray}{exec}, and \colorbox{lightgray}{run} with this directory just as you would with a Singularity image. You can also write files to this directory from within a Singularity session (provided you have the permissions to do so). These files will be ephemeral and will disappear when the container is finished executing. However if you use the \colorbox{lightgray}{-{}-writable} option the changes will be saved into your directory so that you can use them the next time you use your container.
\subsubsubsection{Writable Image}
If you prefer to have a writable image file, you can \colorbox{lightgray}{build} a container with the \colorbox{lightgray}{-{}-writable} option.\\
\begin{lstlisting}[frame=single]
$ sudo singularity build --writable ubuntu.img docker://ubuntu
\end{lstlisting}
This produces an image that is writable with an ext3 file system. Unlike the sandbox, it is a single image file. Also by convention this file name has an “.img” extension instead of “.simg” .\\
When you want to alter your image, you can use commands like \colorbox{lightgray}{shell}, \colorbox{lightgray}{exec}, \colorbox{lightgray}{run}, with the \colorbox{lightgray}{-{}-writable} option. Because of permission issues it may be necessary to execute the container as root to modify it.
\begin{lstlisting}[frame=single]
$ sudo singularity shell --writable ubuntu.img
\end{lstlisting}
\subsubsubsection{Converting images from one format to another}
The \colorbox{lightgray}{build} command allows you to build a container from an existing container. This means that you can use it to convert a container from one format to another. For instance, if you have already created a sandbox (directory) and want to convert it to the default immutable image format (squashfs) you can do so:\\
\begin{lstlisting}[frame=single]
$ singularity build new-squashfs sandbox
\end{lstlisting}
Doing so may break reproducibility if you have altered your sandbox outside of the context of a recipe file, so you are advised to exercise care.\\
You can use \colorbox{lightgray}{build} to convert containers to and from \colorbox{lightgray}{writable}, \colorbox{lightgray}{sandbox}, and default (squashfs) file formats via any of the six possible combinations.
\subsubsubsection{Singularity Recipes}
For a reproducible, production-quality container, we recommend that you build a container with the default (squashfs) file format using a Singularity recipe file. This also makes it easy to add files, environment variables, and install custom software, and still start from your base of choice (e.g., Singularity Hub).\\
A recipe file has a header and a body. The header determines what kind of base container to begin with, and the body is further divided into sections (called scriptlets) that do things like install software, setup the environment, and copy files into the container from the host system.\\
Here is an example of a recipe file:
\begin{lstlisting}[frame=single]
Bootstrap: shub
From: singularityhub/ubuntu
%runscript
exec echo "The runscript is the containers default runtime command!"
%files
/home/vanessa/Desktop/hello-kitty.txt # copied to root of container
/home/vanessa/Desktop/party_dinosaur.gif /opt/the-party-dino.gif #
%environment
VARIABLE=MEATBALLVALUE
export VARIABLE
%labels
AUTHOR vsochat@stanford.edu
%post
apt-get update && apt-get -y install python3 git wget
mkdir /data
echo "The post section is where you can install, and configure your container."
\end{lstlisting}
To build a container from this definition file (assuming it is a file named Singularity), you would call build like so:
\begin{lstlisting}[frame=single]
$ sudo singularity build ubuntu.simg Singularity
\end{lstlisting}
In this example, the header tells singularity to use a base Ubuntu image from Singularity Hub. The \colorbox{lightgray}{\%runscript} section defines actions for the container to take when it is executed (in this case a simple message). The \colorbox{lightgray}{\%files} section copies some files into the container from the host system at build time. The \colorbox{lightgray}{\%environment} section defines some environment variables that will be available to the container at runtime. The \colorbox{lightgray}{\%labels} section allows for custom metadata to be added to the container. And finally the \colorbox{lightgray}{\%post} section executes within the container at build time after the base OS has been installed. The \colorbox{lightgray}{\%post} section is therefore the place to perform installations of custom apps.\\
This is a very small example of the things that you can do with a \hyperref[sec:recipefile]{{\textcolor{cyan}{recipe file}}}. In addition to building a container from Singularity Hub, you can start with base images from Docker Hub, use images directly from official repositories such as Ubuntu, Debian, Centos, Arch, and BusyBox, use an existing container on your host system as a base, or even take a snapshot of the host system itself and use that as a base image.\\
If you want to build Singularity images without having singularity installed in a build environment, you can build images using \href{https://github.com/singularityhub/singularityhub.github.io/wiki}{Singularity Hub} instead. If you want a more detailed rundown and examples for different build options, see our \hyperref[sec:singularityflow]{{\textcolor{cyan}{singularity flow}}} page.
\subsection{Introduction}
\begin{flushleft}
\scriptsize{These docs are for Singularity Version 2.5.1. For older versions, see our archive}
\end{flushleft}
This document will introduce you to Singularity, and the links in the bar to the left will give you more detail on using the software. If you want to get a quick rundown, see our quickstart. If you want to understand which commands are best fit for your usecase, see our build flow page. There is also a separate Singularity Administration Guide that targets system administrators, so if you are a service provider, or an interested user, it is encouraged that you read that document as well.
\subsubsection{Welcome to Singularity!}
Singularity is a container solution created by necessity for scientific and application driven workloads.
\\[0.2in]
Over the past decade and a half, virtualization has gone from an engineering toy to a global infrastructure necessity and the evolution of enabling technologies has flourished. Most recently, we have seen the introduction of the latest spin on virtualization… “containers”. People tend to view containers in light of their virtual machine ancestry and these preconceptions influence feature sets and expected use cases. This is both a good and a bad thing...
\\[0.2in]
For industry and enterprise-centric container technologies this is a good thing. Web enabled cloud requirements are very much in alignment with the feature set of virtual machines, and thus the preceding container technologies. But the idea of containers as miniature virtual machines is a bad thing for the scientific world and specifically the high performance computation (HPC) community. While there are many overlapping requirements in these two fields, they differ in ways that make a shared implementation generally incompatible. Some groups have leveraged custom-built resources that can operate on a lower performance scale, but proper integration is difficult and perhaps impossible with today’s technology.
\\[0.2in]
Many scientists could benefit greatly by using container technology, but they need a feature set that differs somewhat from that available with current container technology. This necessity drives the creation of Singularity and articulated its four primary functions:
\subsubsubsection{Mobility Of Compute}
Mobility of compute is defined as the ability to define, create and maintain a workflow and be confident that the workflow can be executed on different hosts, operating systems (as long as it is Linux) and service providers. Being able to contain the entire software stack, from data files to library stack, and portably move it from system to system is true mobility.
\\[0.2in]
Singularity achieves this by utilizing a distributable image format that contains the entire container and stack into a single file. This file can be copied, shared, archived, and standard UNIX file permissions also apply. Additionally containers are portable (even across different C library versions and implementations) which makes sharing and copying an image as easy as \colorbox{lightgray}{cp} or \colorbox{lightgray}{scp} or \colorbox{lightgray}{ftp}.
\subsubsubsection{Reproducibility}
As mentioned above, Singularity containers utilize a single file which is the complete representation of all the files within the container. The same features which facilitate mobility also facilitate reproducibility. Once a contained workflow has been defined, the container image can be snapshotted, archived, and locked down such that it can be used later and you can be confident that the code within the container has not changed.
\subsubsubsection{User Freedom}
System integrators, administrators, and engineers spend a lot of effort maintaining their systems, and tend to take a cautious approach. As a result, it is common to see hosts installed with production, mission critical operating systems that are “old” and have few installed packages. Users may find software or libraries that are too old or incompatible with the software they must run, or the environment may just lack the software stack they need due to complexities with building, specific software knowledge, incompatibilities or conflicts with other installed programs.
\\[0.2in]
Singularity can give the user the freedom they need to install the applications, versions, and dependencies for their workflows without impacting the system in any way. Users can define their own working environment and literally copy that environment image (single file) to a shared resource, and run their workflow inside that image.
\subsubsubsection{Support On Existing Traditional HPC}
Replicating a virtual machine cloud like environment within an existing HPC resource is not a reasonable goal for many administrators. There are a lots of container systems available which are designed for enterprise, as a replacement for virtual machines, are cloud focused, or require unstable or unavailable kernel features.
\\[0.2in]
Singularity supports existing and traditional HPC resources as easily as installing a single package onto the host operating system. Custom configurations may be achieved via a single configuration file, and the defaults are tuned to be generally applicable for shared environments.
\\[0.2in]
Singularity can run on host Linux distributions from RHEL6 (RHEL5 for versions lower than 2.2) and similar vintages, and the contained images have been tested as far back as Linux 2.2 (approximately 14 years old). Singularity natively supports InfiniBand, Lustre, and works seamlessly with all resource managers (e.g. SLURM, Torque, SGE, etc.) because it works like running any other command on the system. It also has built-in support for MPI and for containers that need to leverage GPU resources.
\subsubsection{A High Level View of Singularity}
\subsubsubsection{Security and privilege escalation}
\label{sec:securityandpriviledge}
A user inside a Singularity container is the same user as outside the container
\\[0.2in]
This is one of Singularities defining characteristics. It allows a user (that may already have shell access to a particular host) to simply run a command inside of a container image as themselves. Here is a scenario to help articulate this:
\\
\begin{quote}
\%SERVER and \%CLUSTER are large expensive systems with resources far exceeding those of my personal workstation. But because the are shared systems, no users have root access. The environments are tightly controlled and managed by a staff of system administrators. To keep these systems secure, only the system administrators are granted root access and they control the state of the operating systems and installed applications. If a user is able to escalate to root (even within a container) on \%SERVER or \%CLUSTER, they can do bad things to the network, cause denial of service to the host (as well as other hosts on the same network), and may have unrestricted access to file systems reachable by the container.
\end{quote}
To mitigate security concerns like this, Singularity limits one’s ability to escalate permission inside a container. For example, if I do not have root access on the target system, I should not be able to escalate my privileges within the container to root either. This is semi-antagonistic to Singularity’s 3rd tenant; allowing the users to have freedom of their own environments. Because if a user has the freedom to create and manipulate their own container environment, surely they know how to escalate their privileges to root within that container. Possible means could be setting the root user’s password, or enabling themselves to have sudo access. For these reasons, Singularity prevents user context escalation within the container, and thus makes it possible to run user supplied containers on shared infrastructures.
\\[0.2in]
This mitigation dictates the Singularity \hyperref[sec:singularityflow]{{\textcolor{cyan}{workflow}}}. If a user needs to be root in order to make changes to their containers, then they need to have an endpoint (a local workstation, laptop, or server) where they have root access. Considering almost everybody at least has a laptop, this is not an unreasonable or unmanageable mitigation, but it must be defined and articulated.
\subsubsubsection{The Singularity container image}
Singularity makes use of a container image file, which physically contains the container. This file is a physical representation of the container environment itself. If you obtain an interactive shell within a Singularity container, you are literally running within that file.
\\[0.2in]
This simplifies management of files to the element of least surprise, basic file permission. If you either own a container image, or have read access to that container image, you can start a shell inside that image. If you wish to disable or limit access to a shared image, you simply change the permission ACLs to that file.
\\[0.2in]
There are numerous benefits for using a single file image for the entire container:
\begin{itemize}
\item Copying or branching an entire container is as simple as \colorbox{lightgray}{cp}
\item Permission/access to the container is managed via standard file system permissions
\item Large scale performance (especially over parallel file systems) is very efficient
\item No caching of the image contents to run (especially nice on clusters)
\item Containers are compressed and consume very little disk space
\item Images can serve as stand-alone programs, and can be executed like any other program on the host
\end{itemize}
\paragraph{\textit{Copying, sharing, branching, and distributing your image}}
A primary goal of Singularity is mobility. The single file image format makes mobility easy. Because Singularity images are single files, they are easily copied and managed. You can copy the image to create a branch, share the image and distribute the image as easily as copying any other file you control!
\\[0.2in]
If you want an automated solution for building and hosting your image, you can use our container registry \href{https://singularity-hub.org/}{Singularity Hub}. Singularity Hub can automatically build \hyperref[sec:recipefiles]{{\textcolor{cyan}{Singularity recipe files}}} from a GitHub repository each time that you push. It provides a simple cloud solution for storing and sharing your image. If you want to host your own Registry, then you should check out \href{https://www.github.com/singularityhub/sregistry}{Singularity Registry}. If you have ideas or suggestions for how Singularity can better support reproducible science, please \href{https://www.sylabs.io/contact/}{reach out!}.
\paragraph{\textit{Supported container formats}}
\begin{itemize}
\item \textbf{squashfs}: the default container format is a compressed read-only file system that is widely used for things like live CDs/USBs and cell phone OS’s
\item \textbf{ext3}: (also called \colorbox{lightgray}{writable}) a writable image file containing an ext3 file system that was the default container format prior to Singularity version 2.4
\item \textbf{directory}: (also called \colorbox{lightgray}{sandbox}) standard Unix directory containing a root container image
\item \textbf{tar.gz}: zlib compressed tar archive
\item \textbf{tar.bz2}: bzip2 compressed tar archive
\item \textbf{tar}: uncompressed tar archive
\end{itemize}
\paragraph{\textit{Supported URIs}}
Singularity also supports several different mechanisms for obtaining the images using a standard URI format.
\begin{itemize}
\item \textbf{shub://} Singularity Hub is our own registry for Singularity containers. If you want to publish a container, or give easy access to others from their command line, or enable automatic builds, you should build it on \href{https://singularity-hub.org/}{Singularity Hub}.
\item \textbf{docker://} Singularity can pull Docker images from a Docker registry, and will run them non-persistently (e.g. changes are not persisted as they can not be saved upstream). Note that pulling a Docker image implies assembling layers at runtime, and two subsequent pulls are not guaranteed to produce an identical image.
\item \textbf{instance://} A Singularity container running as service, called an instance, can be referenced with this URI.
\end{itemize}
\subsubsubsection{Name-spaces and isolation}
When asked, “What namespaces does Singularity virtualize?”, the most appropriate response from a Singularity use case is “As few as possible!”. This is because the goals of Singularity are mobility, reproducibility and freedom, not full isolation (as you would expect from industry driven container technologies). Singularity only separates the needed namespaces in order to satisfy our primary goals.
\\[0.2in]
Coupling incomplete isolation with the fact that a user inside a container is the same user outside the container, allows Singularity to blur the lines between a container and the underlying host system. Using Singularity feels like running in a parallel universe, where there are two timelines. In one timeline, the system administrators installed their operating system of choice. But on an alternate timeline, we bribed the system administrators and they installed our favorite operating system and apps, and gave us full control but configured the rest of the system identically. And Singularity gives us the power to pick between these two timelines.
\\[0.2in]
In other words, Singularity allows you to virtually swap out the underlying operating system for one that you’ve defined without affecting anything else on the system and still having all of the host resources available to us.
\\[0.2in]
It’s like ssh’ing into another identical host running a different operating system. One moment you are on Centos-6 and the next minute you are on the latest version of Ubuntu that has Tensorflow installed, or Debian with the latest OpenFoam, or a custom workflow that you installed. But you are still the same user with the same files running the same PIDs.
\\[0.2in]
Additionally, the selection of name-space virtualization can be dynamic or conditional. For example, the PID namespace is not separated from the host by default, but if you want to separate it, you can with a command line (or environment variable) setting. You can also decide you want to contain a process so it can not reach out to the host file system if you don’t know if you trust the image. But by default, you are allowed to interface with all of the resources, devices and network inside the container as you are outside the container.
\\
\subsubsubsection{Compatibility with standard work-flows,pipes and IO}
Singularity abstracts the complications of running an application in an environment that differs from the host. For example, applications or scripts within a Singularity container can easily be part of a pipeline that is being executed on the host. Singularity containers can also be executed from a batch script or other program (e.g. an HPC system’s resource manager) natively.
\\[0.2in]
Some usage examples of Singularity can be seen as follows:
\begin{lstlisting}[frame=single]
$ singularity exec dummy.img xterm # run xterm from within the container
$ singularity exec dummy.img python script.py # run a script on the host system using container's python
$ singularity exec dummy.img python < /path/to/python/script.py # do the same via redirection
$ cat /path/to/python/script.py | singularity exec dummy.img python # do the same via a pipe
\end{lstlisting}
You can even run MPI executables within the container as simply as:
\begin{lstlisting}[frame=single]
$ mpirun -np X singularity exec /path/to/container.img /usr/bin/mpi_program_inside_container (mpi program args)
\end{lstlisting}
\subsubsubsection{The Singularity Process Flow}
When executing container commands, the Singularity process flow can be generalized as follows:
\begin{enumerate}
\item Singularity application is invoked
\item Global options are parsed and activated
\item The Singularity command (subcommand) process is activated
\item Subcommand options are parsed
\item The appropriate sanity checks are made
\item Environment variables are set
\item The Singularity Execution binary is called (\colorbox{lightgray}{sexec})
\item Sexec determines if it is running privileged and calls the \colorbox{lightgray}{SUID} code if necessary
\item Namespaces are created depending on configuration and process requirements
\item The Singularity image is checked, parsed, and mounted in the namespace
\item Bind mount points are setup so that files on the host are visible in the \colorbox{lightgray}{CLONE\_NEWNS} container
\item The namespace \colorbox{lightgray}{CLONE\_FS} is used to virtualize a new root file system
\item Singularity calls \colorbox{lightgray}{execvp()} and Singularity process itself is replaced by the process inside the container
\item When the process inside the container exits, all namespaces collapse with that process, leaving a clean system
\end{enumerate}
All of the above steps take approximately 15-25 thousandths of a second to run, which is fast enough to seem instantaneous.
\subsubsection{The Singularity Usage Workflow}
The security model of Singularity (as described above, \hyperref[sec:securityandpriviledge]{{\textcolor{cyan}{"A user inside a Singularity container is the same user as outside the container"}}}) defines the Singularity workflow. There are generally two groups of actions you must implement on a container; management (building your container) and usage.\\[0.1in]
In many circumstances building containers require root administrative privileges just like these actions would require on any system, container, or virtual machine. This means that a user must have access to a system on which they have root privileges. This could be a server, workstation, a laptop, virtual machine, or even a cloud instance. If you are using OS X or Windows on your laptop, it is recommended to setup Vagrant, and run Singularity from there (there are recipes for this which can be found at Once you have Singularity installed on your endpoint of choice, this is where you will do the bulk of your container development.
This workflow can be described visually as follows:
\\[0.1in]
\begin{figure}[h]
\centering
\hspace*{-0.62in}
%\includegraphics[width=0.5,height=0.5]{flow.png}
\includegraphics{flow.png}
\caption{Singularity workflow}
\end{figure}
On the left side, you have your build environment: a laptop, workstation, or a server that you control. Here you will (optionally):
\\
\begin{enumerate}
\item develop and test containers using \colorbox{lightgray}{- -sandbox} (build into a writable directory) or \colorbox{lightgray}{- -writable} (build into a writable ext3 image)
\item build your production containers with a squashfs filesystem.
\end{enumerate}
Once you have the container with the necessary applications, libraries and data inside it can be easily shared to other hosts and executed without requiring root access. A production container should be an immutable object, so if you need to make changes to your container you should go back to your build system with root privileges, rebuild the container with the necessary changes, and then re-upload the container to the production system where you wish to run it.
\subsubsubsection{Singularity Commands}
How do the commands work? Here is where to look for more information:
\\[0.1in]
\begin{itemize}
\item \hyperref[sec:build]{{\textcolor{cyan}{build}}}: Build a container on your user endpoint or build environment
\item \hyperref[sec:exec]{{\textcolor{cyan}{exec}}}: Execute a command to your container
\item \hyperref[sec:inspect]{{\textcolor{cyan}{inspect}}}: See labels, run and test scripts, and environment variables
\item \hyperref[sec:pull]{{\textcolor{cyan}{pull}}}: pull an image from Docker or Singularity Hub
\item \hyperref[sec:run]{{\textcolor{cyan}{run}}}: Run your image as an executable
\item \hyperref[sec:shell]{{\textcolor{cyan}{shell}}}: Shell into your image
\end{itemize}
\noindent\textbf{Image Commands}
\begin{itemize}
\item \hyperref[sec:imageimport]{{\textcolor{cyan}{image.import}}}: import layers or other file content to your image
\item \hyperref[sec:imageexport]{{\textcolor{cyan}{image.export}}}: export the contents of the image to tar or stream
\item \hyperref[sec:imagecreate]{{\textcolor{cyan}{image.create}}}: create a new image, using the old ext3 filesystem
\item \hyperref[sec:imageexpand]{{\textcolor{cyan}{image.expand}}}: increase the size of your image (old ext3)
\end{itemize}
\noindent\textbf{Instance Commands}
\\[0.2in]
\hfill Instances were added in 2.4. This list is brief, and likely to expand with further development.
\begin{itemize}
\item \hyperref[sec:instances]{{\textcolor{cyan}{instances}}}: Start, stop, and list
container instances
\end{itemize}
\noindent\textbf{Deprecated Commands} The following commands are deprecated in 2.4 and will be removed in future releases.
\begin{itemize}
\item \hyperref[sec:bootstrap]{{\textcolor{cyan}{bootstrap}}}: Bootstrap a container recipe
\end{itemize}
\subsubsection{Support}
Have a question, or need further information? \href{http://singularity.lbl.gov/support}{Reach out to us}.
\subsection{Installation}
\label{sec:installation}
This document will guide you through the process of installing Singularity from source with the version and location of your choice.
\subsubsection{Before you begin}
If you have an earlier version of Singularity installed, you should remove it before executing the installation commands.
\\[0.1in]
These instructions will build Singularity from source on your system. So you will need to have some development tools installed. If you run into missing dependencies, try installing them like so:\\
\subsubsubsection{Ubuntu}
\begin{lstlisting}[frame=single]
$ sudo apt-get update && \
sudo apt-get install \
python \
dh-autoreconf \
build-essential \
libarchive-dev
\end{lstlisting}
\subsubsubsection{Centos}
\begin{lstlisting}[frame=single]
$ sudo yum update && \
sudo yum groupinstall 'Development Tools' && \
sudo yum install libarchive-devel
\end{lstlisting}
\subsubsection{Install the master branch}
The following commands will install the latest version of the \href{https://github.com/singularityware/singularity}{GitHub repo} master branch to \colorbox{lightgray}{/usr/local}.
\begin{lstlisting}[frame=single]
$ git clone https://github.com/singularityware/singularity.git
$ cd singularity
$ ./autogen.sh
$ ./configure --prefix=/usr/local --sysconfdir=/etc
$ make
$ sudo make install
\end{lstlisting}
Note that the installation prefix is \colorbox{lightgray}{/usr/local} but the configuration directory is \colorbox{lightgray}{/etc}. This ensures that the configuration file \colorbox{lightgray}{singularity.conf} is placed in the standard location.\\
If you omit the \colorbox{lightgray}{-{}-sysconfdir} option , the configuration file will be installed in \colorbox{lightgray}{/usr/local/etc}. If you omit the \colorbox{lightgray}{-{}-prefix} option, Singularity will be installed in the \colorbox{lightgray}{/usr/local} directory hierarchy by default. And if you specify a custom directory with the \colorbox{lightgray}{-{}-prefix} option, all of Singularity’s binaries and the configuration file will be installed within that directory. This last option can be useful if you want to install multiple versions of Singularity, install Singularity on a shared system, or if you want to remove Singularity easily after installing it.
\\
\subsubsection{Install a specific release}
The following commands will install a specific release from
\href{https://github.com/singularityware/singularity/releases}{GitHub releases} page to \colorbox{lightgray}{/usr/local}.\\[0.1in]
\begin{lstlisting}[frame=single]
$ VER=2.5.1
$ wget https://github.com/singularityware/singularity/releases/download/$VER/singularity-$VER.tar.gz
$ tar xvf singularity-$VER.tar.gz
$ cd singularity-$VER
$ ./configure --prefix=/usr/local --sysconfdir=/etc
$ make
$ sudo make install
\end{lstlisting}
\subsubsection{Install the development branch}
If you want to test a development branch the routine above should be tweaked slightly:\\
\begin{lstlisting}[frame=single]
$ git clone https://github.com/singularityware/singularity.git
$ cd singularity
$ git fetch
$ git checkout development
$ ./autogen.sh
$ ./configure --prefix=/usr/local --sysconfdir=/etc
$ make
$ sudo make install
\end{lstlisting}
\subsubsection{Remove an old version}
Let’s say that we installed Singularity to \colorbox{lightgray}{/usr/local}. To remove it completely, you need to hit all of the following:
\begin{lstlisting}[frame=single]
$ sudo rm -rf /usr/local/libexec/singularity
$ sudo rm -rf /usr/local/etc/singularity
$ sudo rm -rf /usr/local/include/singularity
$ sudo rm -rf /usr/local/lib/singularity
$ sudo rm -rf /usr/local/var/lib/singularity/
$ sudo rm /usr/local/bin/singularity
$ sudo rm /usr/local/bin/run-singularity
$ sudo rm /usr/local/etc/bash_completion.d/singularity
$ sudo rm /usr/local/man/man1/singularity.1
\end{lstlisting}
If you modified the system configuration directory, remove the \colorbox{lightgray}{singularity.conf} file there as well.\\
If you installed Singularity in a custom directory, you need only remove that directory to uninstall Singularity. For instance if you installed singularity with the \colorbox{lightgray}{-{}-prefix=/some/temp/dir} option argument pair, you can remove Singularity like so:
\begin{lstlisting}[frame=single]
$ sudo rm -rf /some/temp/dir
\end{lstlisting}
What should you do next? You can check out the \hyperref[sec:quickstart]{{\textcolor{cyan}{quickstart}}} guide, or learn how to interact with your container via the \hyperref[sec:shell]{{\textcolor{cyan}{shell}}}, \hyperref[sec:exec]{{\textcolor{cyan}{exec}}} , or \hyperref[sec:run]{{\textcolor{cyan}{run}}} commands. Or click \textbf{next} below to continue reading.
\subsection{Build a Container}
\label{sec:buildcontainer}
\colorbox{lightgray}{build} is the “Swiss army knife” of container creation. You can use it to download and assemble existing containers from external resources like \href{https://singularity-hub.org/}{Singularity Hub} and \href{https://hub.docker.com/}{Docker Hub}. You can use it to convert containers between the various formats supported by Singularity. And you can use it in conjunction with a \hyperref[sec:recipefile]{{\textcolor{cyan}{Singularity recipe}}} file to create a container from scratch and customized it to fit your needs.
\subsubsection{Overview}
The \colorbox{lightgray}{build} command accepts a target as input and produces a container as output.\\
The target defines the method that \colorbox{lightgray}{build} uses to create the container. It can be one of the following:\\
\begin{itemize}
\item URI beginning with \textbf{shub://} to build from Singularity Hub
\item URI beginning with \textbf{docker://} to build from Docker Hub
\item path to a \textbf{existing container} on your local machine
\item path to a \textbf{directory} to build from a sandbox
\item path to an \textbf{archive} in .tar or compressed .tar.gz format
\item path to a \textbf{\hyperref[sec:recipefile]{{\textcolor{cyan}{Singularity recipe file}}}}
\end{itemize}
In addition \colorbox{lightgray}{build} can produce containers in three different formats. Formats types can be specified by passing the following options to build.
\\
\begin{itemize}
\item compressed read-only \textbf{squashfs} file system suitable for production (default)
\item writable \textbf{ext3} file system suitable for interactive development ( \colorbox{lightgray}{-{}-writable} option )
\item writable \textbf{(ch)root directory} called a sandbox for interactive development (\colorbox{lightgray}{-{}-sandbox} option)
\end{itemize}
Because \colorbox{lightgray}{build} can accept an existing container as a target and create a container in any of these three formats you can convert existing containers from one format to another.\\
The following diagram illustrates the targets that can be supplied to \colorbox{lightgray}{build} as inputs and the containers \colorbox{lightgray}{build} can produce as outputs. Green arrows represent operations that can be carried out without root privileges (though the container may not perform properly when run as root). Red arrows represent operations that must be carried out with root privileges.
\begin{figure}[h]
\centering
\hspace*{-0.62in}
%\includegraphics[width=0.5,height=0.5]{build_input_output.png}
\includegraphics{build_input_output.png}
\caption{Singularity build process}
\end{figure}
\subsubsection{Downloading a existing container from Singularity Hub}
You can use the build command to download a container from Singularity Hub.
\begin{lstlisting}[frame=single]
$ singularity build lolcow.simg shub://GodloveD/lolcow
\end{lstlisting}
The first argument (\colorbox{lightgray}{lolcow.simg}) specifies a path and name for your container. The second argument \\(\colorbox{lightgray}{shub://GodloveD/lolcow}) gives the Singularity Hub URI from which to download.\\
But default the container will be converted to a compressed, read-only squashfs file. If you want your container in a different format use the \colorbox{lightgray}{-{}-writable} or \colorbox{lightgray}{-{}-sandbox} options.
\subsubsection{Downloading a existing container from Docker Hub}
You can use \colorbox{lightgray}{build} to download layers from Docker Hub and assemble them into Singularity containers.
\begin{lstlisting}[frame=single]
$ singularity build lolcow.simg docker://godlovedc/lolcow
\end{lstlisting}
\subsubsection{Creating - -writable images and - -sandbox directories}
\subsubsubsection{- -writable}
If you wanted to create a writable ext3 image similar to those used by Singularity version < 2.4, you could do so with the \colorbox{lightgray}{-{}-writable} option. You must create writable containers as root.
\\[0.1in]
Extending the Singularity Hub example from above:
\begin{lstlisting}[frame=single]
$ sudo singularity build --writable lolcow.img shub://GodloveD/lolcow
\end{lstlisting}
The resulting container is writable, but is still mounted as read-only when executed with commands such as \colorbox{lightgray}{run}, \colorbox{lightgray}{exec}, and \colorbox{lightgray}{shell}. To mount the container as read-write when using these commands add the \colorbox{lightgray}{-{}-writable} option to them as well.\\[0.1in]
To ensure that you have the proper permissions to write to the container as you like, it is also a good idea to make changes as root. For example:
\begin{lstlisting}[frame=single]
$ sudo singularity shell --writable lolcow.img
\end{lstlisting}
\subsubsubsection{- -sandbox}
If you wanted to create a container within a writable directory (called a sandbox) you could do so with the \colorbox{lightgray}{-{}-sandbox} option. It’s possible to create a sandbox without root privileges, but to ensure proper file permissions it is recommended to do so as root.
\begin{lstlisting}[frame=single]
$ sudo singularity build --sandbox lolcow/ shub://GodloveD/lolcow
\end{lstlisting}
The resulting directory operates just like a container in an image file. You are permitted to make changes and write files within the directory, but those changes will not persist when you are finished using the container. To make your changes persistent, use the \colorbox{lightgray}{-{}-writable} flag when you invoke your container.
\\[0.1in]
Once again, it’s a good idea to do this as root to ensure you have permission to access the files and directories that you want to change.
\begin{lstlisting}[frame=single]
$ sudo singularity shell --writable lolcow/
\end{lstlisting}
\subsubsection{Converting containers from one format to another}
If you already have a container saved locally, you can use it as a target to build a new container. This allows you convert containers from one format to another. For example if you had a squashfs container called \colorbox{lightgray}{production.simg} and wanted to convert it to a writable ext3 container called \colorbox{lightgray}{development.img} you could:
\begin{lstlisting}[frame=single]
$ sudo singularity build --writable development.img production.simg
\end{lstlisting}
Similarly, to convert it to a writable directory (a sandbox):\\[0.1in]
\begin{lstlisting}[frame=single]
$ singularity build --sandbox development/ production.simg
\end{lstlisting}
If you omit any options you can also convert your sandbox back to a read-only compressed squashfs image suitable for use in a production environment:
\begin{lstlisting}[frame=single]
$ singularity build production2 development/
\end{lstlisting}
You can convert the three supported container formats using any combination.\\[0.1in]
Use care when converting writable ext3 images or sandbox directories to the default squashfs file format. If changes were made to the writable container before conversion, there is no record of those changes in the Singularity recipe file rendering your container non-reproducible. It is a best practice to build your immutable production containers directly from a Singularity recipe file instead.
\subsubsection{Building containers from Singularity recipe files}
Of course, Singularity recipe files can be used as the target when building a container. For detailed information on writing Singularity recipe files, please see the \hyperref[sec:recipefile]{{\textcolor{cyan}{Container Recipes docs}}}.\\
Let’s say you already have the following container recipe file called \colorbox{lightgray}{Singularity}, and you want to use it to build a container.
\begin{lstlisting}[frame=single]
Bootstrap: docker
From: ubuntu:16.04
%post
apt-get -y update
apt-get -y install fortune cowsay lolcat
%environment
export LC_ALL=C
export PATH=/usr/games:$PATH
%runscript
fortune | cowsay | lolcat
\end{lstlisting}
You can do so with the following command.
\begin{lstlisting}[frame=single]
$ sudo singularity build lolcow.simg Singularity
\end{lstlisting}
The command requires \colorbox{lightgray}{sudo} just as installing software on your local machine requires root privileges.
\subsubsubsection{- -force}
You can build into the same container multiple times (though the results may be unpredictable and it is generally better to delete your container and start from scratch).\\[0.1in]
By default if you build into an existing container, the \colorbox{lightgray}{build} command will skip the steps involved in adding a new base. You can override this default with the \colorbox{lightgray}{-{}-force} option requiring that a new base OS is bootstrapped into the existing container. This behavior does not delete the existing OS, it just adds the new OS on top of the existing one.\\[0.1in]
Use care with this option: you may get results that you did not expect.
\subsubsubsection{- -section}
If you only want to build a single section of your Singularity recipe file use the \colorbox{lightgray}{-{}-section} option. For instance, if you have edited the \colorbox{lightgray}{\%environment} section of a long Singularity recipe and don’t want to completely re-build the container, you could re-build only the \ \colorbox{lightgray}{\%environment} section like so:
\begin{lstlisting}[frame=single]
$ sudo singularity build --section environment image.simg Singularity
\end{lstlisting}
Under normal build conditions, the Singularity recipe file is saved into a container’s meta-data so that there is a record showing how the container was built. Using the \colorbox{lightgray}{-{}-section} option may render this meta-data useless, so use care if you value reproducibility.
\subsubsubsection{- -notest}
If you don’t want to run the \colorbox{lightgray}{\%test} section during the container build, you can skip it with the \colorbox{lightgray}{-{}-notest} option. For instance, maybe you are building a container intended to run in a production environment with GPUs. But perhaps your local build resource does not have GPUs. You want to include a \colorbox{lightgray}{\%test} section that runs a short validation but you don’t want your build to exit with an error because it cannot find a GPU on your system.
\begin{lstlisting}[frame=single]
$ sudo singularity build GPU.simg --notest Singularity
\end{lstlisting}
\subsubsubsection{- -checks}
Checks are a new feature (in 2.4) that offer an easy way for an admin to define a security (or any other kind of check) to be run on demand for a Singularity image. They are defined (and run) via different tags.\\[0.1in]
\begin{lstlisting}[frame=single]
CHECKS OPTIONS:
-c|--checks enable checks
-t|--tag specify a check tag (not default)
-l|--low Specify low threshold (all checks, default)
-m|--med Perform medium and high checks
-h|--high Perform only checks at level high
\end{lstlisting}
When you add the \colorbox{lightgray}{-{}-checks} option along with applicable tags to the \colorbox{lightgray}{build} command Singularity will run the desired checks on your container at build time. See \colorbox{lightgray}{singularity check --help} for available tags.
\subsubsection{More Build topics}
\begin{itemize}
\item If you want to \textbf{customize the cache location} (where Docker layers are downloaded on your system), specify Docker credentials, or any custom tweaks to your build environment, see \hyperref[sec:buildenv]{{\textcolor{cyan}{build environment}}}.
\item If you want to make internally \textbf{modular containers}, check out the getting started guide \href{https://sci-f.github.io/tutorials}{here}
\item If you want to \textbf{build your containers} on Singularity Hub, (because you don’t have root access on a Linux machine or want to host your container on the cloud) check out \href{https://github.com/singularityhub/singularityhub.github.io/wiki}{this guide}
\end{itemize}
\subsection{Build Environment}
\label{sec:buildenv}
It’s commonly the case that you want to customize your build environment, such as specifying a custom cache directory for layers, or sending your Docker Credentials to the registry endpoint. Here we will discuss those things
\subsubsection{Cache Folders}
To make download of layers for build and \hyperref[sec:pull]{{\textcolor{cyan}{pull}}} faster and less redundant, we use a caching strategy. By default, the Singularity software will create a set of folders in your \colorbox{lightgray}{\$HOME} directory for docker layers, Singularity Hub images, and Docker metadata, respectively:
\begin{lstlisting}[frame=single]
$HOME/.singularity
$HOME/.singularity/docker
$HOME/.singularity/shub
$HOME/.singularity/metadata
\end{lstlisting}
Fear not, you have control to customize this behavior! If you don’t want the cache to be created (and a temporary directory will be used), set \colorbox{lightgray}{SINGULARITY\_DISABLE\_CACHE} to True/yes, or if you want to move it elsewhere, set \colorbox{lightgray}{SINGULARITY\_CACHEDIR} to the full path where you want to cache. Remember that when you run commands as sudo this will use root’s home at \colorbox{lightgray}{/root} and not your user’s home.
\subsubsection{Temporary Folders}
\label{sec:temporaryfolders}
Singularity also uses some temporary directories to build the squashfs filesystem, so this temp space needs to be large enough to hold the entire resulting Singularity image. By default this happens in \colorbox{lightgray}{/tmp} but can be overridden by setting \colorbox{lightgray}{SINGULARITY\_TMPDIR} to the full path where you want the squashfs temp files to be stored. Since images are typically built as root, be sure to set this variable in root’s environment.
\\[0.1in]
If you are building an image on the fly, for example
\begin{lstlisting}[frame=single]
singularity exec docker://busybox /bin/sh
\end{lstlisting}
by default a temporary runtime directory is created that looks like \colorbox{lightgray}{/tmp/.singularity-runtime.xxxxxxxx}. This can be problematic for some \colorbox{lightgray}{/tmp} directories that are hosted at Jetstream/OpenStack, Azure, and possibly EC2, which are very small. If you need to change the location of this runtime, then \textbf{export} the variable\\ \colorbox{lightgray}{\$SINGULARITY\_LOCALCACHEDIR}.
\begin{lstlisting}[frame=single]
SINGULARITY_LOCALCACHEDIR=/tmp/pancakes
export SINGULARITY_LOCALCACHEDIR
singularity exec docker://busybox /bin/sh
\end{lstlisting}
The above runtime folder would be created under\\[0.1in]
\colorbox{lightgray}{/tmp/pancakes/.singularity-runtime.xxxxxxxx}