You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: pages/docs/contributing/contributing-docs.md
+11-1Lines changed: 11 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,12 +3,14 @@ title: Contributing to Documentation
3
3
sidebar: main_sidebar
4
4
permalink: contributing-docs
5
5
folder: releases
6
+
toc: false
6
7
---
7
8
8
9
We (like almost all open source software providers) have a documentation dillemma... We tend to focus on the code features and functionality before working on documentation. And there is very good reason for this, we want to share the love so nobody feels left out!
9
10
10
11
The following documentation page assumes one is running on OS X, but if you are not, you should be able to easily transpose the necessary commands to your operating system of choice.
Make sure to resize your terminal to 25 rows x 115 columns or less before you
119
+
begin your recording. Otherwise it will not display properly on the webpage. To get the size of your current terminal (in lines and columns) you can use `tput`:
116
120
117
-
Once you've generated an asciicast, you should drop the file (e.g., some `demo-asciicast.js`) into the `assets/asciicast` folder, and then include the following in the page or post:
121
+
```
122
+
echo -e "lines\ncols"|tput -S
123
+
34
124
+
80
125
+
```
126
+
127
+
Once you've generated an asciicast, you should drop the file (e.g., `demo-asciicast.js`) into the `assets/asciicast` folder. Since we will have many asciicasts here, please name it meaningfully. Then include the following in the page or post:
118
128
119
129
```bash
120
130
{{ "{% include asciicast.html source='demo-asciicast.js' title='How to make demos' author='[email protected]'" }}%}
Copy file name to clipboardExpand all lines: pages/docs/overview/faq.md
+4-1Lines changed: 4 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -213,7 +213,10 @@ See the Singularity on HPC page for more details.
213
213
214
214
### Does Singularity support containers that require GPUs?
215
215
216
-
Yes, Singularity has been tested to run some test and diagnostic code from within a container without modification. There are however potential issues that can come into play when using GPUs, for instance there are version API compatibilities between kernel and user land which will have to be considered.
216
+
Yes. Many users run GPU dependant code within Singularity containers. The
217
+
experimental `--nv` option allows you to leverage host GPUs without installing
218
+
system level drivers into your container. See the [`exec`](/docs-exec#a-gpu-example) command for
Copy file name to clipboardExpand all lines: pages/docs/user-docs/docs-bootstrap-image.md
+12-2Lines changed: 12 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,9 +3,9 @@ title: Getting Started with Bootstrap
3
3
sidebar: user_docs
4
4
permalink: bootstrap-image
5
5
folder: docs
6
+
toc: false
6
7
---
7
8
8
-
## Bootstrapping a Container
9
9
Bootstrapping is the process where we install an operating system and then configure it appropriately for a specified need. To do this we use a bootstrap definition file (a text file called `Singularity`) which is a recipe of how to specifically build the container. Here we will overview the sections, best practices, and a quick example.
10
10
11
11
{% include toc.html %}
@@ -142,7 +142,17 @@ Version 2.0
142
142
```
143
143
144
144
#### %environment
145
-
Akin to labels, you can add pairs of `VARIABLE` and `VALUE` under environment to be sourced when the container is used as variables in the environment. The entire section is written to a file that gets sourced, so you should generally use the same conventions that you might use in a `bashrc` or `profile`. See <ahref="/docs-environment-metadata">Environment and Metadata</a> for more information about these two sections.
145
+
You can add environment variables to be sourced when the container is used in the `%environment` section. The entire section is written to a file that gets sourced, so you should generally use the same conventions that you might use in a `bashrc` or `profile`.
146
+
147
+
```
148
+
%environment
149
+
VADER=badguy
150
+
LUKE=goodguy
151
+
SOLO=someguy
152
+
export VADER LUKE SOLO
153
+
```
154
+
155
+
See <ahref="/docs-environment-metadata">Environment and Metadata</a> for more information about the `%labels` and `%environment` sections.
Copy file name to clipboardExpand all lines: pages/docs/user-docs/docs-bootstrap.md
+13-7Lines changed: 13 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,10 +6,10 @@ toc: false
6
6
folder: docs
7
7
---
8
8
9
-
{% include toc.html %}
10
-
11
9
The process of *bootstrapping* a Singularity container is equivalent to describing a recipe for the container creation. There are several recipe formats that Singularity supports, but only the primary format of version 2.3 will be documented here. If you want a general overview with examples, see <ahref="/bootstrap-image">Bootstrapping an Image</a>. The detailed options for each of the header and sections are provided here.
12
10
11
+
{% include toc.html %}
12
+
13
13
## The header fields:
14
14
15
15
### Bootstrap:
@@ -48,7 +48,7 @@ The Docker bootstrap module will create a core operating system image based on a
48
48
Once the `Bootstrap` module has completed, the sections are identified and utilized if present. The following sections are supported in the bootstrap definition, and integrated during the bootstrap process:
49
49
50
50
51
-
####%setup
51
+
### %setup
52
52
This section blob is a Bourne shell scriptlet which will be executed on the host outside the container during bootstrap. The path to the container is accessible from within the running scriptlet environment via the variable `$SINGULARITY_ROOTFS`. For example, consider the following scriptlet:
53
53
54
54
```
@@ -65,8 +65,7 @@ As we investigate this example scriptlet, you will first see this is the outside
65
65
66
66
*note: Any uncaught command errors that occur within the scriptlet will cause the entire build process to halt!*
67
67
68
-
69
-
#### %post
68
+
### %post
70
69
Similar to the `%setup` section, this section will be executed once during bootstrapping, but this scriptlet will be run from inside the container. This is where you should put additional installation commands, downloads, and configuration into your containers. Here is an example to consider:
71
70
72
71
```
@@ -94,8 +93,15 @@ The above example runs inside the container, so in this case we will first insta
94
93
95
94
*another note: This is not a good example of a reproducible definition because it is pulling Open MPI from a moving target. A better example, would be to pull a static released version, but this serves as a good example of building a `%post` scriptlet.*
96
95
96
+
### %environment
97
+
Beginning with Singularity v2.3 you can set up your environment using the `%environment` section of the definition file. For example, if you wanted to add a directory to your search path, you could do so like this.
98
+
99
+
```
100
+
%environment
101
+
export PATH=/opt/good/stuff:$PATH
102
+
```
97
103
98
-
####%runscript
104
+
### %runscript
99
105
The `%runscript` is another scriptlet, but it does not get executed during bootstrapping. Instead it gets persisted within the container to a file called `/singularity` which is the execution driver when the container image is ***run*** (either via the `singularity run` command or via executing the container directly).
100
106
101
107
When the `%runscript` is executed, all options are passed along to the executing script at runtime, this means that you can (and should) manage argument processing from within your runscript. Here is an example of how to do that:
@@ -108,7 +114,7 @@ When the `%runscript` is executed, all options are passed along to the executing
108
114
109
115
In this particular runscript, the arguments are printed as a single string (`$*`) and then they are passed to `/usr/bin/python` via a quoted array (`$@`) which ensures that all of the arguments are properly parsed by the executed command. The `exec` command causes the given command to replace the current entry in the process table with the one that is to be called. This makes it so the runscript shell process ceases to exist, and the only process running inside this container is the called Python command.
110
116
111
-
####%test
117
+
### %test
112
118
You may choose to add a `%test` section to your definition file. This section will be run at the very end of the boostrapping process and will give you a chance to validate the container during the bootstrap process. If you are building on Singularity Hub, [it is a good practice](https://github.com/singularityhub/singularityhub.github.io/wiki/Generate-Images#add-tests) to have this test section so you can be sure that your container works as expected. A non-zero status code indicates that one or more of your tests did not pass. You can also execute this scriptlet through the container itself, such that you can always test the validity of the container itself as you transport it to different hosts. Extending on the above Open MPI `%post`, consider this example:
Copy file name to clipboardExpand all lines: pages/docs/user-docs/docs-environment-metadata.md
+8-7Lines changed: 8 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,15 +1,16 @@
1
1
---
2
-
title: Changing Existing Containers
2
+
title: Environment and Metadata
3
3
sidebar: user_docs
4
4
permalink: docs-environment-metadata
5
5
folder: docs
6
+
toc: false
6
7
---
7
8
8
-
## Container Metadata
9
+
Singularity containers support environment variables and labels that can be added by user during the bootstrap process.
9
10
10
-
Singularity containers have two level of metadata - environment variables, and labels from the user and bootstrap process.
11
+
{% include toc.html %}
11
12
12
-
###Environment
13
+
## Environment
13
14
14
15
If you are importing a Docker container, the environment will be imported as well. If you want to define custom environment variables in your bootstrap recipe file `Singularity` you can do that like this
15
16
@@ -18,8 +19,8 @@ Bootstrap:docker
18
19
From: ubuntu:latest
19
20
20
21
%environment
21
-
VARIABLE_NAME=VARIABLE_VALUE
22
-
export VARIABLE_NAME
22
+
VARIABLE_NAME=VARIABLE_VALUE
23
+
export VARIABLE_NAME
23
24
```
24
25
25
26
Forget something, or need a variable defined at runtime? You can set any variable you want inside the container by prefixing it with "SINGULARITYENV_". It will be transposed automatically and the prefix will be stripped. For example, let's say we want to set the variable `HELLO` to have value `WORLD`. We can do that as follows:
Copy file name to clipboardExpand all lines: pages/docs/user-docs/docs-exec.md
+56-63Lines changed: 56 additions & 63 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,69 +8,11 @@ toc: false
8
8
9
9
The `exec` Singularity sub-command allows you to spawn an arbitrary command within your container image as if it were running directly on the host system. All standard IO, pipes, and file systems are accessible via the command being exec'ed within the container. Note that this exec is different from the Docker exec, as it does not require a container to be "running" before using it.
2017-08-18 20:33:59.677580: W tensorflow/core/platform/cpu_feature_guard.cc:45] The TensorFlow library wasn't compiled to use SSE4.1 instructions, but these are available on your machine and could speed up CPU computations.
114
+
2017-08-18 20:33:59.677620: W tensorflow/core/platform/cpu_feature_guard.cc:45] The TensorFlow library wasn't compiled to use SSE4.2 instructions, but these are available on your machine and could speed up CPU computations.
115
+
2017-08-18 20:34:00.148531: I tensorflow/stream_executor/cuda/cuda_gpu_executor.cc:893] successful NUMA node read from SysFS had negative value (-1), but there must be at least one NUMA node, so returning NUMA node zero
116
+
2017-08-18 20:34:00.148926: I tensorflow/core/common_runtime/gpu/gpu_device.cc:955] Found device 0 with properties:
117
+
name: GeForce GTX 760 (192-bit)
118
+
major: 3 minor: 0 memoryClockRate (GHz) 0.8885
119
+
pciBusID 0000:03:00.0
120
+
Total memory: 2.95GiB
121
+
Free memory: 2.92GiB
122
+
2017-08-18 20:34:00.148954: I tensorflow/core/common_runtime/gpu/gpu_device.cc:976] DMA: 0
123
+
2017-08-18 20:34:00.148965: I tensorflow/core/common_runtime/gpu/gpu_device.cc:986] 0: Y
124
+
2017-08-18 20:34:00.148979: I tensorflow/core/common_runtime/gpu/gpu_device.cc:1045] Creating TensorFlow device (/gpu:0) -> (device: 0, name: GeForce GTX 760 (192-bit), pci bus id: 0000:03:00.0)
Copy file name to clipboardExpand all lines: pages/docs/user-docs/docs-export.md
+8-16Lines changed: 8 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,24 +6,16 @@ toc: false
6
6
folder: docs
7
7
---
8
8
9
-
Export is a way to dump the contents of your container into a .tar.gz, or a stream to put into some other place. For example, you could stream this into an in memory tar in python.
9
+
Export is a way to dump the contents of your container into a .tar.gz, or a stream to put into some other place. For example, you could stream this into an in memory tar in python.
0 commit comments