Merge pull request #121 from GodloveD/DCG-edits2

DCG edits

Author: vsoch

_data/sidebars/user_docs.yml

@@ -23,7 +23,7 @@ entries:
       url: /quickstart
       output: web, pdf
 
-    - title: Build an Image
+    - title: Build a Container
       url: /docs-build
       output: web, pdf
 

assets/img/diagram/build_input_output.svg

@@ -6,21 +6,21 @@ toc: false
 folder: docs
 ---
 
-{% include toc.html %}
+Singularity allows you to map directories on your host system to directories within your container using bind mounts.  This allows you to read and write data on the host system with ease.
 
-## Bind Paths
-Singularity 'swaps' out the currently running root operating system on the host for what is inside the container, and in doing so none of the host file systems are accessible anymore. As a workaround for this, Singularity will *bind* those paths back in via two primary methods: system defined bind points and conditional user defined bind points.
+{% include toc.html %}
 
-{% include asciicast.html source='docs-create-rootmount.js' uid='how-to-mount-and-copy' title='How to mount an image and copy files to it' author='davidgodlove@gmail.com'%}
+## Overview
+When Singularity 'swaps' the host operating system for the one inside your container, the host file systems becomes inaccessible. But you may want to read and write files on the host system from within the container. To enable this functionality Singularity will *bind* directories  back in via two primary methods: system defined bind points and conditional user defined bind points.
 
-To *mount* a bind path inside the container, a ***bind point*** must be defined within the container. The bind point is a target location entity to which the actual directory or file can be bound to. This means that if you want to bind to a point within the container such as `/global`, that directory must already exist within the container.
+To *mount* a bind path inside the container, a **bind point** must be defined within the container. The bind point is a directory within the container that Singularity can use to bind a directory on the host system.  This means that if you want to bind to a point within the container such as `/global`, that directory must already exist within the container.
 
-It is however possible that the system administrator has enabled a Singularity feature called *overlay* in the `/etc/singularity/singularity.conf` file. This will cause the bind points to be created on an as needed basis in an overlay file system so that the underlying container is not modified. But because the *overlay* feature is not always used, it maybe necessary for container standards to exist to ensure portability from host to host.
+It is however possible that the system administrator has enabled a Singularity feature called *overlay* in the `/etc/singularity/singularity.conf` file. This will cause the bind points to be created on an as needed basis so that the underlying container is not modified. But because the *overlay* feature is not always used or unavailable in some kernels, it maybe necessary for container standards to exist to ensure portability from host to host.
 
-If a bind path is requested, and the bind point does not exist within the container, a warning message will be displayed, and Singularity will continue trying to mount file system. For example:
+If a bind path is requested, and the bind point does not exist within the container, a warning message will be displayed, and Singularity will continue trying to start the container. For example:
 
 ```bash
-$ singularity shell /tmp/Centos7-ompi.img 
+$ singularity shell --bind /global /tmp/Centos7-ompi.img 
 WARNING: Non existant bind point (directory) in container: '/global'
 Singularity: Invoking an interactive shell within container...
 
@@ -30,17 +30,17 @@ Singularity.Centos7-ompi.img>
 Even though `/global` did not exist inside the container, the shell command printed a warning but continued on. If we enable `enable overlay = yes` in the `/etc/singularity/singularity.conf` you will find that we no longer get the error and `/global` is created and accessible as expected:
 
 ```bash
-$ singularity shell /tmp/Centos7-ompi.img 
+$ singularity shell --bind /global /tmp/Centos7-ompi.img 
 Singularity: Invoking an interactive shell within container...
 
 Singularity.Centos7-ompi.img> 
 ```
 
-#### System defined bind points
+### System defined bind points
 The system administrator has the ability to define what bind points will be included automatically inside each container. The bind paths are locations on the host's root file system which should also be visible within the container. Some of the bind paths are automatically derived (e.g. a user's home directory) and some are statically defined (e.g. `bind path = ` in `/etc/singularity/singularity.conf`).
 
 
-#### User defined bind points
+### User defined bind points
 If the system administrator has enabled user control of binds (via `user bind control = yes` in `/etc/singularity/singularity.conf`), you will be able to request your own bind points within your container. 
 
 Further, if the administrator has enabled the use of file system overlay (via `enable overlay = yes` in `/etc/singularity/singularity.conf`), you can bind host system directories to directories that do not exist within the container.  Singularity will dynamically create the necessary bind points in your container on demand.  This feature may not be supported on older host systems.

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

@@ -6,14 +6,18 @@ folder: docs
 toc: false
 ---
 
-New to Singularity 2.4 is the ability to, on demand, run container "checks," which can be anything from a filter for sensitive information, to an analysis of content on the filesystem. Checks are installed with Singularity and [managed by the administration](/docs-admin-checks), however as a user they are accessible to you for use during bootstrap or on demand:
+New to Singularity 2.4 is the ability to run container "checks" on demand. Checks can be anything from a filter for sensitive information, to an analysis installed binaries. A few defualt checks are installed with Singularity and others can be [added by the administrater](/docs-admin-checks).  Users can perform checks at build time or on demand:
 
+{% include toc.html %}
+
+Perform all default checks, these are the same
 ```
-# Perform all default checks, these are the same
 $ singularity check ubuntu.img
 $ singularity check --tag default ubuntu.img
+```
 
-# Perform checks with tag "clean"
+Perform checks with tag "clean"
+```
 $ singularity check --tag clean ubuntu.img
 ```
 
@@ -29,7 +33,7 @@ USAGE
 
 EXAMPLE
 
-singularity check --tag docker ubuntu.img
+$ singularity check --tag docker ubuntu.img
 ```
 
 If you want to run checks associated with a different security level, you can specify with `--low`, `--med`, or `-high`:

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

@@ -6,36 +6,40 @@ folder: docs
 toc: false
 ---
 
-Singularity containers support environment variables and labels that can be added by user during the bootstrap process.
+Singularity containers support environment variables and labels that you can add to your container during the build process.
 
 {% include toc.html %}
 
 ## Environment
 
-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
+If you build a container from Singularity Hub or Docker Hub, the environment will be included with the container at build time. You can also define custom environment variables in your Recipe file like so:
 
-```bash
-Bootstrap:docker
-From: ubuntu:latest
+```
+Bootstrap: shub
+From: vsoch/hello-world
 
 %environment
     VARIABLE_NAME=VARIABLE_VALUE
     export VARIABLE_NAME
 ```
 
-If you need to add an environment variable to your container during the `%post` section, you can do so using the `$SINGULARITY_ENVIRONMENT` variable with the following syntax:
+You may need to add environment variables to your container during the `%post` section.  For instance, maybe you will not know the appropriate value of a variable until you have installed some software.  
+
+To add variables to the environment during `%post` you can use the `$SINGULARITY_ENVIRONMENT` variable with the following syntax:
 
 ```
 %post
     echo 'export VARIABLE_NAME=VARIABLE_VALUE' >>$SINGULARITY_ENVIRONMENT
 ```
 
-Text in the `%environment` section will be appended to the file `/.singularity.d/env/90-environment.sh` while text redirected to `$SINGULARITY_ENVIRONMENT` will end up in the file `/.singularity.d/env/91-environment.sh`.  Because files in `/.singularity.d/env` are sourced in alpha-numerical order, this means that variables added using `$SINGULARITY_ENVIRONMENT` take precedence over those added via the `%environment` section.
+Text in the `%environment` section will be appended to the file `/.singularity.d/env/90-environment.sh` while text redirected to `$SINGULARITY_ENVIRONMENT` will end up in the file `/.singularity.d/env/91-environment.sh`.  
+
+Because files in `/.singularity.d/env` are sourced in alpha-numerical order, this means that variables added using `$SINGULARITY_ENVIRONMENT` take precedence over those added via the `%environment` section.
 
-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:
+Need to define a variable at runtime? You can set variables inside the container by prefixing them with "SINGULARITYENV_". They 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:
 
-```bash
-$ SINGULARITYENV_HELLO=WORLD singularity exec -e centos7.img env
+```
+$ SINGULARITYENV_HELLO=WORLD singularity exec --cleanenv centos7.img env
 HELLO=WORLD
 LD_LIBRARY_PATH=:/usr/local/lib:/usr/local/lib64
 SINGULARITY_NAME=test.img
@@ -47,32 +51,13 @@ SINGULARITY_INIT=1
 SINGULARITY_CONTAINER=test.img
 ```
 
-Notice the `-e`? That is the argument (or `--cleanenv`) that specifies that we want to remove the host environment from the container. If we remove the `-e`, we will still pass forward `HELLO=WORLD`, and the list shown above, but we will also pass forward all the other environment variables from the host. Here is a command to directly echo the variable we define:
-
-```bash
-$echo 'echo $HELLO' | SINGULARITYENV_HELLO=WORLD singularity exec centos7.img /bin/sh
-WORLD
-```
-
-If you want to look at the environment inside a container, you can look inside the metadata env folder as follows:
-
-```bash
-singularity exec centos7.img ls /.singularity.d/env
-01-base.sh  10-docker.sh  99-environment.sh
-```
-
-The variables in `01-base.sh` are a set of defaults set upon container creation, and the `10-docker.sh` come from a Docker import.
-
-```bash
-singularity exec centos7.img cat /.singularity.d/env/10-docker.sh
-export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
-```
+Notice the `--cleanenv` in the example above? That argument specifies that we want to remove the host environment from the container. If we remove the `--cleanenv`, we will still pass forward `HELLO=WORLD`, and the list shown above, but we will also pass forward all the other environment variables from the host. 
 
 ## Labels
-Your container stores metadata about it's build, along with Docker labels, and your custom labels that you define in a bootstrap `%labels` section. For containers that are generated with Singularity version 2.4 and later, labels are represented using the <a href="http://label-schema.org/rc1/">rc1 Label Schema</a>. For example:
+Your container stores metadata about it's build, along with Docker labels, and custom labels that you define during build in a `%labels` section. For containers that are generated with Singularity version 2.4 and later, labels are represented using the <a href="http://label-schema.org/rc1/">rc1 Label Schema</a>. For example:
 
 ```
-singularity inspect dino.img
+$ singularity inspect dino.img
 {
     "org.label-schema.usage.singularity.deffile.bootstrap": "docker",
     "MAINTAINER": "Vanessasaurus",
@@ -87,10 +72,9 @@ singularity inspect dino.img
 }
 ```
 
-You will notice that the one label doesn't belong to the label schema, `MAINTAINER`. This was a user provided label during bootstrap. Finally, for Singularity greater than version 2.4, the image build size is added as a label, `org.label-schema.build-size`, and the label schema is used, period. For versions earlier than 2.4, containers did not use the label schema, and looked like this:
-
+You will notice that the one label doesn't belong to the label schema, `MAINTAINER`. This was a user provided label during bootstrap. Finally, for Singularity versions >= 2.4, the image build size is added as a label, `org.label-schema.build-size`, and the label schema is used througout. For versions earlier than 2.4, containers did not use the label schema, and looked like this:
 
-```bash
+```
 singularity exec centos7.img cat /.singularity.d/labels.json
 { "name": 
       "CentOS Base Image", 
@@ -102,13 +86,46 @@ singularity exec centos7.img cat /.singularity.d/labels.json
 
 You can add custom labels to your container in a bootstrap file:
 
-```bash
+```
 Bootstrap: docker
 From: ubuntu: latest
 
 %labels
 
 AUTHOR Vanessasaur
 ```
+The `inspect` command is useful for viewing labels and other container meta-data.  
+
+## Container Metadata
+
+Inside of the container, metadata is stored in the `/.singularity.d` directory. You probably shouldn't edit any of these files directly but it may be helpful to know where they are and what they do:
+
+```
+/.singularity.d/
+├── actions
+│   ├── exec
+│   ├── run
+│   ├── shell
+│   ├── start
+│   └── test
+├── env
+│   ├── 01-base.sh
+│   ├── 90-environment.sh
+│   ├── 95-apps.sh
+│   └── 99-base.sh
+├── labels.json
+├── libs
+├── runscript
+├── Singularity
+└── startscript
+```
+
+- **actions**: This directory contains helper scripts to allow the container to carry out the action commands.
+- **env**:  All *.sh files in this directory are sourced in alpha-numeric order when the container is initiated. For legacy purposes there is a symbolic link called `/environment` that points to `/.singularity.d/env/90-environment.sh`.
+- **labels.json**: The json file that stores a containers labels described above.
+- **libs**: At runtime the user may request some host-system libraries to be mapped into the container (with the `--nv` option for example). If so, this is their destination.  
+- **runscript**: The commands in this file will be executed when the container is invoked with the `run` command or called as an executable. For legacy purposes there is a symbolic link called `/singularity` that points to this file
+- **Singularity**: This is the Recipe file that was used to generate the container. If more than 1 Recipe file was used to generate the conainer additional Singularity files will appear in numeric order in a sub-directory called `bootstrap_history`
+- **startscript**: The commands in this file will be executed when the container is invoked with the `instance.start` command.  
 
 {% include links.html %}