Merge branch 'GodloveD-add-build-command' into docs/2.4

Author: vsoch

_data/sidebars/user_docs.yml

@@ -24,7 +24,7 @@ entries:
       output: web, pdf
 
     - title: Build a Container
-      url: /docs-build
+      url: /docs-build-container
       output: web, pdf
 
     - title: Container Recipes

_posts/releases/2017-10-02-release-2.4.md

@@ -17,7 +17,7 @@ Building an image is now more intuitive with the introduction of our `build` com
 sudo singularity build container.simg Singularity
 ```
 
-If you are tired of needing to estimate your image size, that issue goes away with build. The default format for a Singularity image base is now a smaller, compressed file format called **SquashFS**.  This format is also a much better fit for reproducible containers, as it is immutable. For more details, see our [build](/docs-build) documentation.
+If you are tired of needing to estimate your image size, that issue goes away with build. The default format for a Singularity image base is now a smaller, compressed file format called **SquashFS**.  This format is also a much better fit for reproducible containers, as it is immutable. For more details, see our [build](/docs-build-container) documentation.
 
 **Build Bases**
 We originally supported just using an existing distribution package or docker as a base for building images. With 2.4, we have extended that set to include another Singularity image (`localimage`), a Singularity Hub or Registry image (`shub`) or the host operating system (`self`).

pages/docs/user-docs/action-bootstrap.md

@@ -6,11 +6,9 @@ folder: docs
 toc: false
 ---
 
->> Note: The bootstrap command is deprecated for Singularity Version 2.4. You should use <a href="/build" target="_blank">build</a> instead.
+> Note: The bootstrap command is deprecated for Singularity Version 2.4. You should use [build](/build-a-container) instead.
 
-Bootstrapping was the original way (for Singularity versions prior to 2.4) to install an operating system and then configure it appropriately for a specified need. Bootstrap is very similar to build, except that it by default uses an <a href="https://en.wikipedia.org/wiki/Ext3" target="_blank">ext3</a> filesystem and allows for writability. The images unfortunately are not immutable in this way, and can degrade over time. As of 2.4, bootstrap is still supported for Singularity, however we encourage you to use <a href="/build" target="_blank">build</a> instead.
-
-{% include toc.html %}
+Bootstrapping was the original way (for Singularity versions prior to 2.4) to install an operating system and then configure it appropriately for a specified need. Bootstrap is very similar to build, except that it by default uses an <a href="https://en.wikipedia.org/wiki/Ext3" target="_blank">ext3</a> filesystem and allows for writability. The images unfortunately are not immutable in this way, and can degrade over time. As of 2.4, bootstrap is still supported for Singularity, however we encourage you to use [build](/build-a-container) instead.
 
 
 ## Quick Start

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

@@ -6,187 +6,45 @@ folder: docs
 toc: false
 ---
 
-`build` is the "Swiss army knife" of container creation.  You can use it to download and assemble existing containers from external resources like [Singularity Hub](https://singularity-hub.org/) and [Docker Hub](https://hub.docker.com/).  You can use it to convert containers between the various formats supported by Singularity.  And you can use it in conjunction with a [Singularity recipe](/docs-recipes) file to create a container from scratch and customized it to fit your needs. 
+Use `build` to download and assemble existing containers, convert containers from one format to another, or build a container from a [Singularity recipe](/docs-recipes). 
 
 {% include toc.html %}
 
 ## Overview
-The `build` command accepts a target as input and produces a container as output.  
+The `build` command accepts a target as input and produces a container as output.  The target can be a Singularity Hub or Docker Hub URI, a path to an existing container, or a path to a Singularity Recipe file.  The output container can be in squashfs, ext3, or directory format.  
 
-The target defines the method that `build` uses to create the container. It can be one of the following:
+For a complete list of `build` options type `singularity help build`.  For more info on building containers see [Build a Container](docs-build-container).
 
-- URI beginning with **shub://** to build from Singularity Hub
-- URI beginning with **docker://** to build from Docker Hub
-- path to a **existing container** on your local machine
-- path to a **directory** to build from a sandbox
-- path to an **archive** in .tar or compressed .tar.gz format
-- path to a **[Singularity recipe file](docs-recipes)**
-
-In addition `build` can produce containers in three different formats.  Formats types can be specified by passing the following options to build.  
-
-- compressed read-only **squashfs** file system suitable for production (default)
-- writable **ext3** file system suitable for interactive development (`--writable` option)
-- writable **(ch)root directory** called a sandbox for interactive development (`--sandbox` option)
-
-Because `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 `build` as inputs and the containers `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.  
-
-<div style="text-align: center">
-<a href="/assets/img/diagram/build_input_output.svg" target="_blank" class="no-after">
-   <img style="max-width:500px" src="/assets/img/diagram/build_input_output.svg">
-</a>
-</div>
-
-## Downloading a existing container from Singularity Hub
-You can use the `build` command to download a container from Singularity Hub. 
+## Examples 
+### Download an existing container from Singularity Hub or Docker Hub
 
 ```
 $ singularity build lolcow.simg shub://GodloveD/lolcow
-```
-
-The first argument (`lolcow.simg`) specifies a path and name for your container.  The second argument (`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 `--writable` or `--sandbox` options.
-
-## Downloading a existing container from Docker Hub
-You can use `build` to download layers from Docker Hub and assemble them into Singularity containers. 
-
-```
 $ singularity build lolcow.simg docker://godlovedc/lolcow
 ```
 
-The same information applies to containers built from Docker Hub and containers built from Singularity Hub. 
-
-## Creating `--writable` images and `--sandbox` directories
-
-### `--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 `--writable` option.  You must create writable containers as root.
-
-Extending the Singularity Hub example from above:
+### Create `--writable` images and `--sandbox` directories
 
 ```
 $ sudo singularity build --writable lolcow.img shub://GodloveD/lolcow
-
-```
-
-The resulting container is writable, but is still mounted as read-only when executed with commands such as `run`, `exec`, and `shell`.  To mount the container as read-write when using these commands add the `--writable` option to them as well.  
-
-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:
-
-```
-$ sudo singularity shell --writable lolcow.img
-```
-
-### `--sandbox`
-If you wanted to create a container within a writable directory (called a _sandbox_) you could do so with the `--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.
-
-```
 $ sudo singularity build --sandbox lolcow/ shub://GodloveD/lolcow
 ```
 
-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 `--writable` flag when you invoke your container.  
-
-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.
-
-```
-$ sudo singularity shell --writable lolcow/
-```
-
-## 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 `production.simg` and wanted to convert it to a writeable ext3 container called `development.img` you could:
-
+### Convert containers from one format to another
+You can convert the three supported container formats using any combination.
 ```
 $ sudo singularity build --writable development.img production.simg
-```
-
-Similarly, to convert it to a writable directory (a sandbox):
-
-```
 $ singularity build --sandbox development/ production.simg
-```
-
-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:
-
-```
 $ singularity build production2 development/
 ```
-You can convert the three supported container formats using any combination.
-
-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.
-
-## 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 Container Recipes docs](docs-recipes).
-
-Let's say you already have the following container recipe file called `Singularity`, and you want to use it to build a container. 
-
-```
-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
-```
-
-You can do so with the following command.  
+### Build a container from a Singularity recipe
+Given a Singularity Recipe called `Singularity`: 
 
 ```
 $ sudo singularity build lolcow.simg Singularity 
 ```
 
-The command requires `sudo` just as installing software on your local machine requires root privileges. 
-
-### `--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).  
-
-By default if you build into an existing container, the `build` command will skip the steps involved in adding a new base.  You can override this default with the `--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.  
-
-Use care with this option: you may get results that you did not expect. 
-
-### `--section`
-If you only want to build a single section of your Singularity recipe file use the `--section` option.  For instance, if you have edited the `%environment` section of a long Singularity recipe and don't want to completely re-build the container, you could re-build only the `%environment` section like so: 
-
-```
-$ sudo singularity build --section environment image.simg Singularity
-```
-
-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 `--section` option may render this meta-data useless, so use care if you value reproducibility.  
-
-### `--notest`
-If you don't want to run the `%test` section during the container build, you can skip it with the `--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 `%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.
-
-```
-$ sudo singularity build GPU.simg --notest Singularity
-```
-
-### `--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.
-
-```
-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
-```
-
-When you add the `--checks` option along with applicable tags to the `build` command Singularity will run the desired checks on your container at build time.  See `singularity check --help` for available tags.  
-
-
-## More Build topics 
- - If you want to **customize the cache location** (where Docker layers are downloaded on your system), specify Docker credentials, or any custom tweaks to your build environment, see <a href="/build-environment">build environment</a>. 
- - If you want to make internally **modular containers**, check out <a href="http://containers-ftw.org/apps/examples/tutorials/getting-started" target="_blank">this post</a>.
- - If you want to **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 [this guide](https://github.com/singularityhub/singularityhub.github.io/wiki).
-
 <script>
 // Without this, pagination links to exec under repeated build section
 $(document).ready(function() {

pages/docs/user-docs/action-run.md

@@ -59,7 +59,7 @@ When you first create a container, the runscript is defined using the following
  4. If the user has not defined a runscript and the Docker container doesn't have an `ENTRYPOINT`, we look for `CMD`, even if the user hasn't asked for it.
  5. If the user has not deifned a runscript, and there is no `ENTRYPOINT` or `CMD` (or we aren't importing Docker at all) then we default to `/bin/bash`
 
-Here is how you would define the runscript section when you [build](/docs-build) an image:
+Here is how you would define the runscript section when you [build](/docs-build-container) an image:
 
 ```bash
 Bootstrap: docker