docs: add missing content

docs/concepts/oci_image_layout.md

@@ -1 +1,10 @@
-# OCI Image Layout
+# OCI Image Layout
+
+Stacker is a standalone OCI-native container image builder which produces
+images in [OCI Image Layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md)
+format.
+
+    OCI Image Layout Specification
+
+        The OCI Image Layout is the directory structure for OCI content-addressable blobs and location-addressable references (refs).
+        This layout MAY be used in a variety of different transport mechanisms: archive formats (e.g. tar, zip), shared filesystem environments (e.g. nfs), or networked file fetching (e.g. http, ftp, rsync).

docs/concepts/stacker_architecture.md

@@ -1 +1,6 @@
-# Stacker Architecture
+# Stacker Architecture
+
+The following diagram illustrates the relationship between the various
+directives and the internal state maintained during the image build process.
+
+![architecture](../assets/images/illustrations/arch.jpg)

docs/developer_guide/building_stacker.md

@@ -1,4 +1,4 @@
-## Building and Installing Stacker
+# Building and Installing Stacker
 
 ### Go Dependency
 

docs/developer_guide/lxc_usage.md

@@ -0,0 +1,4 @@
+# LXC
+
+stacker uses [lxc](https://github.com/lxc/lxc) as its underlying container
+management library in order to achieve hermetically-sealed image builds.

docs/developer_guide/overlayfs_usage.md

@@ -0,0 +1,7 @@
+# OverlayFS Support
+
+stacker relies on [overlayFS](https://docs.kernel.org/filesystems/overlayfs.html) in the Linux kernel, which should be available in kernel versions 4.x and above.
+
+You can also check by running the command `lsmod | grep overlay` if compiled
+and available as a module or if compiled inline by enabling `CONFIG_OVERLAY_FS`
+in the Linux kernel build configuration.

docs/get_started/get_stacker.md

@@ -1,3 +1,5 @@
+# Installing Stacker
+
 Stacker is a single static binary tool with most of the dependencies built into 
 the binary. Stacker, however, depends on specific kernel capabilities and system
 tools to provide various features.
@@ -67,4 +69,4 @@ This binary needs to be installed and present in `$PATH`.
 
 ```bash title="Install mksquashfs on ubuntu"
 sudo apt-get install -y squashfs-tools
-```
+```

docs/get_started/hello_stacker_image.md

@@ -1,3 +1,5 @@
+# A "Hello Stacker" Image
+
 Stacker builds OCI images using the YAML definition in a file referred to as 
 the stacker file. So let's create a stacker file definition that packages a 
 simple "Hello Stacker!" script into an OCI container image.

docs/reference/stacker_file.md

@@ -1,4 +1,4 @@
-## The `stacker.yaml` file
+# The `stacker.yaml` file
 
 When doing a `stacker build`, the behavior of stacker is specified by the yaml
 directives below. In addition to these, stacker allows variable substitions of

docs/user_guide/annotation_support.md

@@ -0,0 +1,14 @@
+# Additing Annotations 
+
+In the stacker yaml file, `annotations` is a user-specified key value map that will be included in the
+final OCI image. Note that these annotations are included in the image manifest
+itself and not as part of the index.json.
+
+    annotations:
+      a.b.c.key: abc_val
+      p.q.r.key: pqr_val
+
+While `config` section supports a similar `labels`, it is more pertitent to the
+image runtime. On the other hand, `annotations` is intended to be
+image-specific metadata aligned with the
+[annotations in the image spec](https://github.com/opencontainers/image-spec/blob/main/annotations.md).

docs/user_guide/build_cache.md

@@ -0,0 +1,6 @@
+# Build Cache
+
+A build cache with snapshot support is maintained throughout the build process
+in order to store intermediate build artifacts and avoid unnecessary rebuilds.
+Furthermore, you can also avoid rebuilding layers across many stacker build
+invocations by preserving this build cache.

docs/user_guide/build_code.md

@@ -1,3 +1,5 @@
+# Producing Images From Compiled/Built Code
+
 A common first step before building a container image is to build your code in a
 consistent environment. Stacker provides a hermetically sealed environment in a
 build-only container to produce the binaries and other artifacts required for

docs/user_guide/build_environment.md

@@ -1,3 +1,5 @@
+# Hermetically-sealed Build Environment
+
 Stacker builds container images in a canonically defined environment, allowing 
 stacker to guarantee repeatable builds by reproducing the same environment for 
 all the builds for a given version of the stacker file.
@@ -111,7 +113,7 @@ The `docker://zothub.io/tools/busybox:stable` container defines the above file
 system, which has all the necessary utilities like /bin/cat and a basic system
 configuration required to operate most of the Linux utilities.
 
-## Newtworking Setup
+## Networking Setup
 
 Stacker builds the container images in the host network namespace. It bind 
 mounts the host's /etc/resolv.conf into the build container's root file system 

docs/user_guide/debugging.md

@@ -1,3 +1,5 @@
+# Debugging
+
 The first step to trying to find a bug in stacker is to run it with --debug.
 This will give you a stack trace from where (at least in stacker's code) the
 error originated via [github.com/pkg/errors](https://github.com/pkg/errors).

docs/user_guide/dependency_builds.md

@@ -0,0 +1,16 @@
+# Chained Builds With Dependency Tracking
+
+You can split image build directives over multiple files and chain them.
+
+If the `prerequisites` list is present under the `config` key, stacker will
+make sure to build all the layers in the stacker.yaml files found at the paths
+contained in the list. This way stacker supports building multiple
+stacker.yaml files in the correct order.
+
+In this particular case the parent folder of the current folder, let's call it
+`parent`, has 3 subfolders `folder1`, `folder2` and `folder3`, each containing a
+`stacker.yaml` file. The example `config` above is in `parent/folder1/stacker.yaml`.
+
+When `stacker build -f parent/folder1/stacker.yaml` is invoked, stacker would search
+for the other two stacker.yaml files and build them first, before building
+the stacker.yaml specified in the command line.

docs/user_guide/grab_image_content.md

@@ -0,0 +1,17 @@
+# Grab Content From Built Images
+
+After an image is built, you can grab a file from the built image. This is
+useful to inspect the file or its contents to ensure the build process has
+completed properly.
+
+```
+NAME:
+   stacker grab - grabs a file from the layer's filesystem
+
+USAGE:
+   stacker grab <tag>:<path>
+
+<tag> is the tag in a built stacker image to extract the file from.
+
+<path> is the path to extract (relative to /) in the image's rootfs.
+```

docs/user_guide/image_chroot.md

@@ -0,0 +1,21 @@
+# Chrooting Into Built Images
+
+After an image is built, you can run a command in a chroot in that built image.
+
+```
+NAME:
+   stacker chroot - run a command in a chroot
+
+USAGE:
+   stacker chroot [command options] [tag] [cmd]
+
+<tag> is the built tag in the stackerfile to chroot to, or the first tag if
+none is specified.
+
+<cmd> is the command to run, or /bin/sh if none is specified. To specify cmd,
+you must specify a tag.
+
+OPTIONS:
+   --stacker-file value, -f value  the input stackerfile (default: "stacker.yaml")
+   --substitute value              variable substitution in stackerfiles, FOO=bar format
+```

docs/user_guide/inspect_images.md

@@ -0,0 +1,15 @@
+# Inspecting Built Images
+
+All built images are stored in OCI Image Layout, and you can inspect the JSON
+representation of an OCI image after it is built.
+
+```
+NAME:
+   stacker inspect - print the json representation of an OCI image
+
+USAGE:
+   stacker inspect [tag]
+
+<tag> is the tag in the stackerfile to inspect. If none is supplied, inspect
+prints the information on all tags.
+```

docs/user_guide/publish_images.md

@@ -0,0 +1,27 @@
+# Publishing images
+
+After building the image, you can publish the image to an [OCI Distribution
+Spec](https://github.com/opencontainers/distribution-spec/blob/main/spec.md)
+conformant registry.
+
+```
+NAME:
+   stacker publish - publishes OCI images previously built from one or more stacker yaml files
+
+USAGE:
+   stacker publish [command options] [arguments...]
+
+OPTIONS:
+   --stacker-file value, -f value          the input stackerfile (default: "stacker.yaml")
+   --stacker-file-pattern value, -p value  regex pattern to use when searching for stackerfile paths (default: "\\/stacker.yaml$")
+   --search-dir value, -d value            directory under which to search for stackerfiles to publish
+   --url value                             url where to publish the OCI images
+   --username value                        username for the registry where the OCI images are published
+   --password value                        password for the registry where the OCI images are published
+   --skip-tls                              skip tls verify on upstream registry
+   --tag value                             tag to be used when publishing
+   --substitute value                      variable substitution in stackerfiles, FOO=bar format
+   --show-only                             show the images to be published without actually publishing them
+   --force                                 force publishing the images present in the OCI layout even if they should be rebuilt
+   --layer-type value                      set the output layer type (supported values: tar, squashfs); can be supplied multiple times (default: "tar")
+```

docs/user_guide/scratch_image.md

@@ -1,4 +1,4 @@
-# Building container image from scratch
+# Bootsrapping From Other Images
 
 There are a couple of cases where it may be useful to build a layer from
 scratch. For example to derive a new base install of an OS or to build a
@@ -68,4 +68,4 @@ Another way to accomplish something similar is to use a
 
 You can use the first layer as a build env, and copy your binary to a 
 bind-mounted folder. Use overlay_dirs with that same folder to have the binary 
-in the distroless layer.
+in the distroless layer.

docs/user_guide/template_substitution.md

@@ -0,0 +1,17 @@
+# Template Variable Substitution
+
+When doing a `stacker build`, the behavior of stacker is specified by the yaml
+directives below. In addition to these, stacker allows variable substitions of
+several forms. For example, a line like:
+
+    $ONE ${{TWO}} ${{THREE:3}}
+
+When run with `stacker build --substitute ONE=1 --substitute TWO=2` is
+processed in stacker as:
+
+    1 2 3
+
+That is, variables of the form `$FOO` or `${FOO}` are supported, and variables
+with `${FOO:default}` a default value will evaluate to their default if not
+specified on the command line. It is an error to specify a `${FOO}` style
+without a default; to make the default an empty string, use `${FOO:}`.

docs/whats-new.md

@@ -0,0 +1 @@
+# What's New

material/overrides/home.html

@@ -17,7 +17,7 @@ <h1>Stacker Build</h1>
           <a href="{{ 'user_guide/build_environment' | url }}" title="User Guide" class="md-button">
             User Guide
           </a>
-          <h3>Pair this with <a href="https://zotregistry.io">zot</a>, an OCI-native Image Registry</h3>
+          <h3>Pair stacker with <a href="https://zotregistry.io">zot</a>, an OCI-native Image Registry</h3>
         </div>
       </div>
     </div> 

mkdocs.yml

@@ -56,6 +56,7 @@ extra:
     default: latest
 plugins:
   - search
+  - git-revision-date-localized
   - minify:
       minify_html: true
 markdown_extensions:
@@ -90,9 +91,13 @@ markdown_extensions:
   - pymdownx.tasklist:
       custom_checkbox: true
   - pymdownx.tilde
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
 
 nav:
   - Home: index.md
+  - What's New: whats-new.md
   - Get Started:
     - Get Stacker: get_started/get_stacker.md
     - Hello Stacker Image: get_started/hello_stacker_image.md
@@ -101,9 +106,9 @@ nav:
     - Stacker Architecture: concepts/stacker_architecture.md
   - User Guide:
     - Build Environment: user_guide/build_environment.md
-    - Build Code: user_guide/build_code.md
-    - Build Container Image: user_guide/build_container_image.md
-    - Scratch Image: user_guide/scratch_image.md
+    - Code Builds: user_guide/build_code.md
+    - Bootstrapped Container Image: user_guide/scratch_image.md
+    - Multi-Stage Build: user_guide/build_container_image.md
     - Template Substitution: user_guide/template_substitution.md
     - Annotation Support: user_guide/annotation_support.md
     - Dependency Builds: user_guide/dependency_builds.md

requirements.txt

@@ -3,3 +3,4 @@ mkdocs-material==8.5.8
 mkdocs-material-extensions==1.1
 mkdocs-minify-plugin==0.6.1
 mike==1.1.2
+mkdocs-git-revision-date-localized-plugin==1.1.0