From 594299cdca0ca49b11035d19f37b93e7ab175419 Mon Sep 17 00:00:00 2001
From: Ravi Chamarthy <ravi@chamarthy.dev>
Date: Mon, 24 Oct 2022 04:08:16 +0000
Subject: [PATCH] doc: add hello stacker page

Signed-off-by: Ravi Chamarthy <ravi@chamarthy.dev>
---
 docs/get_started/build_image.md         |   1 -
 docs/get_started/hello_stacker_image.md | 131 ++++++++++++++++++++++++
 mkdocs.yml                              |   2 +-
 3 files changed, 132 insertions(+), 2 deletions(-)
 delete mode 100644 docs/get_started/build_image.md
 create mode 100644 docs/get_started/hello_stacker_image.md

diff --git a/docs/get_started/build_image.md b/docs/get_started/build_image.md
deleted file mode 100644
index d04dc0d..0000000
--- a/docs/get_started/build_image.md
+++ /dev/null
@@ -1 +0,0 @@
-# Build Image
diff --git a/docs/get_started/hello_stacker_image.md b/docs/get_started/hello_stacker_image.md
new file mode 100644
index 0000000..1e24212
--- /dev/null
+++ b/docs/get_started/hello_stacker_image.md
@@ -0,0 +1,131 @@
+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.
+
+```yaml title="Hello Stacker"
+hello-stacker:
+  from:
+    type: docker
+    url: docker://ubuntu:latest
+  run: |
+    mkdir -p /hello-stacker-app
+    echo 'echo "Hello Stacker!"' > /hello-stacker-app/hello.sh
+    chmod +x /hello-stacker-app/hello.sh
+  entrypoint: /hello-stacker-app/hello.sh
+
+```
+
+`hello-stacker`, the first key in the above YAML, builds an OCI image named
+__hello-stacker__.
+
+The `from` section defines that `hello-stacker` image builds on top of an 
+existing image called `ubuntu:latest`, and that the base image is of type 
+`docker` downloaded from URL `docker://ubuntu:latest`.
+
+The `run` section defines a build script. This script is executed on top of the
+ubuntu image's root file system, creates a file called 
+`/hello-stacker-app/hello.sh`, and makes it executable.
+
+`entrypoint` defines that `/hello-stacker-app/hello.sh` is executed as the `init`
+process on creating this container by a container runtime.
+
+We can create the `hello-stacker` image with this input as a
+stacker file name `hello_stacker.yaml`.
+
+```bash title="Hello Stacker Build"
+$ stacker build -f hello_stacker.yaml
+preparing image hello-stacker...
+loading docker://ubuntu:latest
+Copying blob cf92e523b49e done
+Copying config cb52c703ef done
+Writing manifest to image destination
+Storing signatures
++ mkdir -p /hello-stacker-app
++ echo echo "Hello Stacker!"
++ chmod +x /hello-stacker-app/hello.sh
+filesystem hello-stacker built successfully
+```
+stacker build used `hello-stacker.yaml` as input, downloaded the `ubuntu:latest`
+image from docker hub and generated an OCI image with tag `hello-stacker`. We 
+can verify this using `stacker inspect`:
+
+```bash title="Stacker Inspect"
+$ stacker inspect
+hello-stacker
+        layer 0: cf92e523b49e... (30 MB, application/vnd.oci.image.layer.v1.tar+gzip)
+        layer 1: 2910d371807c... (176 B, application/vnd.oci.image.layer.v1.tar+gzip)
+Annotations:
+  io.stackeroci.stacker.stacker_yaml: hello-stacker:
+  from:
+    type: docker
+    url: docker://ubuntu:latest
+  run: |
+    mkdir -p /hello-stacker-app
+    echo 'echo "Hello Stacker!"' > /hello-stacker-app/hello.sh
+    chmod +x /hello-stacker-app/hello.sh
+  entrypoint: /hello-stacker-app/hello.sh
+
+
+Image config:
+{
+  "created": "2022-10-24T03:47:24.374578534Z",
+  "author": "stacker-dev",
+  "architecture": "amd64",
+  "os": "linux",
+  "config": {
+    "Env": [
+      "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+    ],
+    "Entrypoint": [
+      "/hello-stacker-app/hello.sh"
+    ]
+  },
+  "rootfs": {
+    "type": "layers",
+    "diff_ids": [
+      "sha256:17f623af01e277c5ffe6779af8164907de02d9af7a0e161662fc735dd64f117b",
+      "sha256:a33ac624796108439088267fb525f1038dccb6f6a50796a1593786a31d97a4bd"
+    ]
+  },
+  "history": [
+    {
+      "created": "2022-10-04T23:35:20.465021967Z",
+      "created_by": "/bin/sh -c #(nop) ADD file:6cd2e13356aa5339c1f2abd3c210a52f6ed74fae05cd61aa09f37b6a4764f65c in / "
+    },
+    {
+      "created": "2022-10-04T23:35:20.857335994Z",
+      "created_by": "/bin/sh -c #(nop)  CMD [\"bash\"]",
+      "empty_layer": true
+    },
+    {
+      "created": "2022-10-24T03:47:24.372946511Z",
+      "created_by": "stacker build of hello-stacker"
+    },
+    {
+      "created": "2022-10-24T03:47:24.374578534Z",
+      "created_by": "stacker build",
+      "author": "root@ins15-pp24-ru11",
+      "empty_layer": true
+    }
+  ]
+}
+```
+
+The next thing to note is that if we rebuild the image without any modifications
+to the stacker file, less things happen:
+
+```bash title="stacker caching"
+$ stacker build -f hello_stacker.yaml
+preparing image hello-stacker...
+loading docker://ubuntu:latest
+Copying blob cf92e523b49e skipped: already exists
+Copying config cb52c703ef done
+Writing manifest to image destination
+Storing signatures
+found cached layer hello-stacker
+```
+
+Stacker will cache all inputs to the stacker file and rebuilds the image only if
+something changed in the stacker file. The cache and the metadata required to 
+track the build state live in the `.stacker` directory where the stacker command 
+is run. Stacker cache can be cleaned using `stacker clean` command.
diff --git a/mkdocs.yml b/mkdocs.yml
index 91d394c..7cee77f 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -88,7 +88,7 @@ nav:
   - Home: index.md
   - Get Started:
     - Get Stacker: get_started/get_stacker.md
-    - Build Image: get_started/build_image.md
+    - Hello Stacker Image: get_started/hello_stacker_image.md
   - Concepts:
     - OCI Image Layout: concepts/oci_image_layout.md
     - Stacker Architecture: concepts/stacker_architecture.md