Skip to content

Commit 427c43e

Browse files
vsochvsoch
committed
more updates to build
1 parent 29fa6e6 commit 427c43e

2 files changed

Lines changed: 94 additions & 73 deletions

File tree

‎_data/sidebars/user_docs.yml‎

Lines changed: 31 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ entries:
1616
output: web, pdf
1717

1818
- title: Installation
19-
url: /docs-quick-start-installation
19+
url: /docs-installation
2020
output: web, pdf
2121

2222
- title: Container Recipes
@@ -55,35 +55,6 @@ entries:
5555
url: /faq#troubleshooting
5656
output: web, pdf
5757

58-
59-
- title: Image Commands
60-
output: web, pdf
61-
62-
- title: image.export
63-
url: /docs-export
64-
output: web, pdf
65-
66-
- title: image.expand
67-
url: /docs-expand
68-
output: web, pdf
69-
70-
- title: image.import
71-
url: /docs-import
72-
output: web, pdf
73-
74-
- title: image.create
75-
url: /docs-create
76-
output: web, pdf
77-
78-
79-
- title: Deprecated
80-
output: web, pdf
81-
82-
- title: bootstrap
83-
url: /docs-bootstrap
84-
output: web, pdf
85-
86-
8758
- title: Commands
8859
output: web, pdf
8960

@@ -116,3 +87,33 @@ entries:
11687
url: /docs-shell
11788
output: web, pdf
11889

90+
91+
- title: Image Commands
92+
output: web, pdf
93+
folderitems:
94+
95+
- title: image.export
96+
url: /docs-export
97+
output: web, pdf
98+
99+
- title: image.expand
100+
url: /docs-expand
101+
output: web, pdf
102+
103+
- title: image.import
104+
url: /docs-import
105+
output: web, pdf
106+
107+
- title: image.create
108+
url: /docs-create
109+
output: web, pdf
110+
111+
112+
- title: Deprecated
113+
output: web, pdf
114+
115+
folderitems:
116+
- title: bootstrap
117+
url: /docs-bootstrap
118+
output: web, pdf
119+

‎pages/docs/user-docs/action-build.md‎

Lines changed: 63 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,15 @@ folder: docs
77

88
Build is the process where we install an operating system and then configure it appropriately for a specified need. To do this we use a [Singularity recipe](/docs-recipes) file (a text file called `Singularity`) which is a recipe of how to specifically build the container. Here we will overview the usage, best practices, and quick examples.
99

10-
- For a detailed **walkhrough of getting started** with build, we will point you to the <a href="/quickstart">quickstart</a>.
11-
- If you want to customize the cache, specify Docker credentials, or any custom tweaks to your build environment, see <a href="/build-environment">build environment</a>.
12-
- If you want to look at how to get started to making interally **modular containers**, check out <a href="http://containers-ftw.org/apps/examples/tutorials/getting-started" target="_blank">this post</a>.
10+
11+
**Getting Started**
12+
For a detailed **walkhrough of getting started** with build, we will point you to the <a href="/quickstart">quickstart</a>.
13+
14+
**Build Environment**
15+
If you want to customize the cache, specify Docker credentials, or any custom tweaks to your build environment, see <a href="/build-environment">build environment</a>.
16+
17+
**Modular Containers**
18+
If you want to look at how to get started to making interally **modular containers**, check out <a href="http://containers-ftw.org/apps/examples/tutorials/getting-started" target="_blank">this post</a>.
1319

1420

1521
{% include toc.html %}
@@ -97,7 +103,7 @@ vanessa@vanessa-ThinkPad-T460s:~/Documents/Dropbox/Code/singularity/singularityw
97103
```
98104

99105
## Usage
100-
here is the usage:
106+
here is the usage. We will break it up into sections so we can talk about each one.
101107

102108
```bash
103109
$ singularity build
@@ -134,8 +140,17 @@ BUILD SPEC TARGET:
134140

135141
shub:// Build from a Singularity registry (Singularity Hub default)
136142
docker:// This points to a Docker registry (Docker Hub default)
143+
```
144+
145+
These "build spec options" refer to the [recipe bases](/docs-recipes#recipes) options that you have.
146+
Generally you are going to be building into a container or folder from some base that is local (an image or directory) or
147+
from an external endpoint (e.g., docker). Next we can look at create options:
137148
149+
## Development (writable) or Production (immutable)?
150+
When you build your container, you probably want a writable container for development, and a nice
151+
immutable one for your completed, production image. Here are the options under the usage (help) for build:
138152
153+
```
139154
CREATE OPTIONS:
140155
-s|--sandbox Build a sandbox rather then a read only compressed image
141156
-w|--writable Build a writable image (warning: deprecated due to sparse
@@ -147,7 +162,33 @@ CREATE OPTIONS:
147162
-s|--section Only run a given section within the bootstrap (setup,
148163
post, files, environment, test, labels, none)
149164

165+
```
166+
167+
You can think of the different options as follows:
150168
169+
**create writable development folder**
170+
```
171+
sudo singularity build --writable container/ Singularity
172+
```
173+
174+
**create writable development ext3 image**
175+
```
176+
sudo singularity build --writable container.img Singularity
177+
```
178+
179+
**create production immutable image**
180+
```
181+
sudo singularity build container.simg Singularity
182+
```
183+
184+
For details about the Singularity flow and use cases, see our [quickstart](/quickstart).
185+
186+
## Checks
187+
Next, we will look at checks. Checks haven't been robustly developed (yet!) but offer
188+
an easy way for an admin to define a security (or any other kind of check) to be run on demand
189+
for a Singularity image. They are defined (and run) via different tags.
190+
191+
```
151192
CHECKS OPTIONS:
152193
-c|--checks enable checks
153194
-t|--tag specify a check tag (not default)
@@ -156,38 +197,14 @@ CHECKS OPTIONS:
156197
-h|--high Perform only checks at level high
157198
158199
See singularity check --help for available tags
159-
160-
DEF FILE BASEOS EXAMPLES:
161-
Singularity Hub:
162-
Bootstrap: shub
163-
From: singularityhub/centos
164-
165-
Docker:
166-
Bootstrap: docker
167-
From: tensorflow/tensorflow:latest
168-
IncludeCmd: yes # Use the CMD as runscript instead of ENTRYPOINT
169-
170-
YUM/RHEL:
171-
Bootstrap: yum
172-
OSVersion: 7
173-
MirrorURL: http://mirror.centos.org/centos-%{OSVERSION}/%{OSVERSION}/os/$basearch/
174-
Include: yum
175-
176-
Debian/Ubuntu:
177-
Bootstrap: debootstrap
178-
OSVersion: trusty
179-
MirrorURL: http://us.archive.ubuntu.com/ubuntu/
180-
181-
Self (copy the host's file system):
182-
Bootstrap: self
183-
184-
Local Image:
185-
Bootstrap: localimage
186-
From: /home/dave/starter.img
200+
```
187201
188202
189-
DEFFILE SECTION EXAMPLES:
203+
## Examples
204+
Let's quickly look at some definition file examples. These come straight from `singularity help build`. First, here
205+
is a recipe for build that serves only to describe the sections.
190206
207+
```
191208
%setup
192209
echo "This is a scriptlet that will be executed on the host, as root, after"
193210
echo "the container has been bootstrapped. To install things into the container"
@@ -225,9 +242,12 @@ DEFFILE SECTION EXAMPLES:
225242
HAN=someguy
226243
export HAN VADER LUKE
227244

245+
```
228246
229-
DEFFILE SCI-F SECTION EXAMPLES:
247+
Now let's look at a recipe that defines different <a href="https://containers-ftw.github.io/apps/" target="_blank">SCI-F apps</a>
230248
249+
250+
```
231251
%appinstall app1
232252
echo "These are steps to install an app using the SCI-F format"
233253
@@ -252,10 +272,12 @@ DEFFILE SCI-F SECTION EXAMPLES:
252272
253273
%apptest app1
254274
echo "some test for an app"
275+
```
255276
277+
## Building
278+
We have a recipe, great! Now how do we build it? In many ways:
256279
257-
EXAMPLES:
258-
280+
```
259281
Build a compressed image from a Singularity recipe file:
260282
$ singularity build /tmp/debian0.simg /path/to/debian.def
261283
@@ -266,15 +288,13 @@ EXAMPLES:
266288
$ singularity build --sandbox /tmp/debian docker://debian:latest
267289
$ singularity exec --writable /tmp/debian apt-get install python
268290
$ singularity build /tmp/debian2.simg /tmp/debian
291+
```
269292
293+
## More Details
294+
- For a detailed **walkhrough of getting started** with build, we will point you to the <a href="/quickstart">quickstart</a>.
295+
- If you want to customize the cache, specify Docker credentials, or any custom tweaks to your build environment, see <a href="/build-environment">build environment</a>.
296+
- If you want to look at how to get started to making interally **modular containers**, check out <a href="http://containers-ftw.org/apps/examples/tutorials/getting-started" target="_blank">this post</a>.
270297
271-
For additional help, please visit our public documentation pages which are
272-
found at:
273-
274-
http://singularity.lbl.gov/
275-
276-
277-
```
278298
279299
## Support
280300
Have a question, or need further information? <a href="/support">Reach out to us.</a>

0 commit comments

Comments
 (0)