Add app dev guide for katacoda

Signed-off-by: Sambhav Kothari <[email protected]>

Author: sambhav

Makefile

@@ -170,4 +170,5 @@ katacoda:
 .PHONY: check-katacoda
 check-katacoda: katacoda
 	@echo "Checking if Katacoda docs are up-to-date..."
-	@git diff --quiet HEAD -- katacoda/scenarios || ( echo "Katacoda docs are not up-to-date! Please run 'make katacoda' and commit the katacoda/scenarios folder" && exit 1)
+	@git diff --quiet HEAD -- katacoda/scenarios || ( echo "Katacoda docs are not up-to-date! Please run 'make katacoda' and commit the katacoda/scenarios folder" && exit 1)
+	@echo "All katacoda docs are up-to-date"

content/docs/app-developer-guide/build-an-app.md

@@ -6,11 +6,15 @@ aliases=[
     "/docs/using-pack/building-app/"
 ]
 +++
-
+<!--+- if false+-->
 <div class="quote mb-4">
     {{< summary "docs/concepts/operations/build.md" >}}
     <div class="author"><a href="/docs/concepts/operations/build">build</a></div>
 </div>
+<!--+- end+-->
+<!--+- `
+# Build an app
+`+-->
 
 Building an app using Cloud Native Buildpacks is as easy as `1`, `2`, `3`...
 
@@ -22,9 +26,10 @@ app.
 
 When using `pack`, you can run `pack builder suggest` for a list of suggested builders.
 
-```bash
+```
 pack builder suggest
 ```
+<!--+- "{{execute}}"+-->
 
 For this guide we're actually going to use a sample builder, `cnbs/sample-builder:bionic`, which is not listed
 as a suggested builder for good reason. It's a sample.
@@ -34,38 +39,62 @@ as a suggested builder for good reason. It's a sample.
 Now that you've decided on what builder to use, we can build our app. For this example we'll use our [samples][samples]
 repo for simplicity.
 
-```bash
-# clone the repo
-git clone https://github.com/buildpacks/samples
+1. Check that the samples repo exists and if not - we clone it
+```
+ls samples || git clone https://github.com/buildpacks/samples
+```
+<!--+- "{{execute}}"+-->
 
-# build the app
+2. Build the app
+```
 pack build sample-app --path samples/apps/java-maven --builder cnbs/sample-builder:bionic
 ```
+<!--+- "{{execute}}"+-->
 
 > **TIP:** If you don't want to keep specifying a builder every time you build, you can set it as your default
-> builder by running `pack config default-builder <BUILDER>`.
+> builder by running `pack config default-builder <BUILDER>` for example `pack config default-builder cnbs/sample-builder:bionic`
+<!--+- "{{execute}}"+-->
 
 ### 3. Run it
 
-```bash
+```
 docker run --rm -p 8080:8080 sample-app
 ```
+<!--+- "{{execute}}"+-->
 
 **Congratulations!**
 
+<!--+- if false+-->
 The app should now be running and accessible via [localhost:8080](http://localhost:8080).
+<!--+end+-->
+
+<!--+ `
+Now open your favorite browser and point it to port "8080" of your host and take a minute to enjoy the view.
+
+On Katacoda you can do this by [clicking here](https://[[HOST_SUBDOMAIN]]-8080-[[KATACODA_HOST]].environments.katacoda.com)
+` +-->
 
 ## What about ARM apps?
 
 Linux ARM image builds are now supported!
 
+<!--+- if false+-->
 <a href="/docs/app-developer-guide/build-an-arm-app" class="button bg-blue">Linux ARM build guide</a>
+<!--+end+-->
 
+<!--+ `
+Check out the [Linux ARM build guide](https://buildpacks.io//docs/app-developer-guide/build-an-arm-app).
+` +-->
 ## What about Windows apps?
 
 Windows image builds are now supported!
 
+<!--+- if false+-->
 <a href="/docs/app-developer-guide/build-a-windows-app" class="button bg-blue">Windows build guide</a>
+<!--+end+-->
+<!--+ `
+Check out the [Windows build guide](https://buildpacks.io/docs/app-developer-guide/build-a-windows-app/).
+` +-->
 
 [build]: /docs/concepts/operations/build
 [builder]: /docs/concepts/components/builder

content/docs/app-developer-guide/environment-variables.md

@@ -3,7 +3,9 @@ title="Environment variables"
 weight=3
 summary="Environment variables are a common way to configure various buildpacks at build-time."
 +++
-
+<!--+- `
+# Environment variables
+`+-->
 Environment variables are a common way to configure various buildpacks at build-time.
 
 Below are a few ways you can do so. All of them will use our [samples][samples] repo for simplicity.
@@ -16,25 +18,30 @@ The `--env` parameter must be one of the following:
 - `VARIABLE`, where the value of `VARIABLE` will be taken from the local environment
 
 ##### Example:
-```bash
-# clone the repo
-git clone https://github.com/buildpacks/samples
 
-# set an environment variable
+1. Set an environment variable
+```
 export FOO=BAR
+```
+<!--+- "{{execute}}"+-->
 
-# build the app
+2. Build the app
+```
 pack build sample-app \
     --env "HELLO=WORLD" \
     --env "FOO" \
     --builder cnbs/sample-builder:bionic \
     --buildpack  samples/buildpacks/hello-world/ \
     --buildpack samples/apps/bash-script/bash-script-buildpack/ \
     --path  samples/apps/bash-script/
+```
+<!--+- "{{execute}}"+-->
 
-# run the app
+3. Run the app
+```
 docker run sample-app
 ```
+<!--+- "{{execute}}"+-->
 
 The following environment variables were set and available to buildpacks at build-time:
 
@@ -52,27 +59,35 @@ The `--env-file` parameter must be a path to a file where each line is one of th
 - `VARIABLE`, where the value of `VARIABLE` will be taken from the current environment
 
 ##### Example:
-```bash
-# clone the repo
-git clone https://github.com/buildpacks/samples
 
-# set an environment variable
+1. Set an environment variable
+```
 export FOO=BAR
+```
+<!--+- "{{execute}}"+-->
 
-# create an env file
+2. Create an env file
+```
 echo -en "HELLO=WORLD\nFOO" > ./envfile
+```
+<!--+- "{{execute}}"+-->
 
-# build the app
+3. Build the app
+```
 pack build sample-app \
     --env-file ./envfile \
     --builder cnbs/sample-builder:bionic \
     --buildpack  samples/buildpacks/hello-world/ \
     --buildpack samples/apps/bash-script/bash-script-buildpack/ \
     --path  samples/apps/bash-script/
+```
+<!--+- "{{execute}}"+-->
 
-# run the app
+4. Run the app
+```
 docker run sample-app
 ```
+<!--+- "{{execute}}"+-->
 
 The following environment variables were set and available to buildpacks at build-time:
 
@@ -81,7 +96,7 @@ The following environment variables were set and available to buildpacks at buil
 | `HELLO` | `WORLD` | _hard-coded value in file_ |
 | `FOO`   | `BAR`   | _current environment_      |
 
-<p class="spacer"></p>
+
 
 > **NOTE:** Variables defined using `--env` take precedence over variables defined in `--env-file`.
 
@@ -91,40 +106,46 @@ Without the `--descriptor` flag, `pack build` will use the `project.toml` file i
 You can define environment variables in an `env` table in the file, and pass those into the application.
 
 ##### Example:
-```bash
-# clone the repo
-git clone https://github.com/buildpacks/samples
 
-# Add an environment variable to the project.toml
+1. Add an environment variable to the project.toml
+
+```
 cat >> samples/apps/bash-script/project.toml <<EOL
+
 [[build.env]]
 name="HELLO"
 value="WORLD"
 EOL
+```
+<!--+- "{{execute}}"+-->
 
-# build the app
+2. Build the app
+```
 pack build sample-app \
     --builder cnbs/sample-builder:bionic \
     --buildpack  samples/buildpacks/hello-world/ \
     --buildpack samples/apps/bash-script/bash-script-buildpack/ \
     --path  samples/apps/bash-script/
+```
+<!--+- "{{execute}}"+-->
 
-# run the app
+3. Run the app
+```
 docker run sample-app
 ```
+<!--+- "{{execute}}"+-->
 
 The following environment variables were set and available to buildpacks at build-time:
 
 | Name    | Value   |  _Source_                  |
 |---------|---------|----------------------------|
 | `HELLO` | `WORLD` | _hard-coded value in file_ |
 
-<p class="spacer"></p>
 
 > **NOTE:** Variables defined using `--env` or `--env-file` take precedence over variables defined in the `project.toml`.
 
 > **NOTE:** `project.toml` can't detect environment variables (so, for instance, if one ran `export FOO=BAR` and added
 >`name=FOO` to the `project.toml`, it wouldn't detect any value set for `FOO`).
 
 [descriptor-schema]: /docs/reference/project-descriptor/
-[samples]: https://github.com/buildpacks/samples
+[samples]: https://github.com/buildpacks/samples

content/docs/app-developer-guide/mounting-volumes.md

@@ -0,0 +1,111 @@
++++
+title="Mounting Volumes"
+weight=4
+summary="Volumes are a mechanism for both supplying and persisting data generated by build containers."
++++
+<!--+if false+-->
+{{< param "summary" >}}
+<!--+end+-->
+<!--+- `
+# Mounting Volumes
+
+Volumes are a mechanism for both supplying and persisting data generated by build containers.
+`+-->
+
+## Mounting Volumes (`--volume`)
+
+The `--volume` parameter must be one of the following:
+
+ - A volume mount.
+ - A comma separated list of volume mounts.
+
+Each volume mount has the following format:
+```
+<host path>:<target path>[:<mode>]
+```
+
+##### `<host path>`
+This is the name of the volume, it is unique on a given host machine.
+
+##### `<target path>`
+The path where the file or directory is available in the container.
+
+##### `[:<mode>]` 
+An optional comma separated list of mount options. If no options are provided, the read-only option will be used.
+A mount option must be one of the following:
+  - `ro`, volume contents are read-only.
+  - `rw`, volume contents are readable and writeable.
+  - `volume-opt=key=value`, can be specified more than once, takes a key-value pair consisting of the option name and its value.
+
+
+### Examples
+For the following examples we will use our [samples][samples] repo for simplicity.
+
+Here we bind mount a local folder into our container and display its contents during 
+a `pack build`.
+
+#### Linux container example
+
+<!-- test:suite=volumes:linux -->
+
+<!-- test:setup:exec -->
+<!--
+```
+git clone https://github.com/buildpack/samples
+```
+-->
+
+<!-- test:teardown:exec -->
+<!--
+```
+docker volume rm test-volume
+```
+-->
+
+We'll create a new docker volume:
+
+<!-- test:exec -->
+```bash
+docker volume create test-volume
+```
+<!--+- "{{execute}}"+-->
+
+Next, we'll create a text file on the volume:
+
+<!-- test:exec -->
+```bash
+docker run --rm \
+    --volume test-volume:/tmp/volume:rw \
+    bash \
+    bash -c 'echo "Hello from a volume!" > /tmp/volume/volume_contents.txt'
+```
+<!--+- "{{execute}}"+-->
+
+Now, we can mount this volume during `pack build`:
+
+<!-- test:exec -->
+```bash
+ls -al
+pack build volume-example \
+    --builder cnbs/sample-builder:bionic \
+    --buildpack samples/buildpacks/hello-world \
+    --path samples/apps/bash-script \
+    --volume test-volume:/platform/volume:ro
+```
+<!--+- "{{execute}}"+-->
+
+The above `pack build ...` command will mount the `test-volume` volume in the `/platform` directory of the container.
+
+Since we are using the `samples/hello-world` buildpack, we should see the `/platform` directory files listed:
+
+```text
+[builder]      platform_dir files:
+...
+[builder]        /platform/volume:
+[builder]        total 12
+[builder]        drwxr-xr-x 2 root root 4096 Sep 17 20:17 .
+[builder]        drwxr-xr-x 1 root root 4096 Sep 17 20:18 ..
+[builder]        -rw-r--r-- 1 root root   21 Sep 17 20:18 volume_contents.txt
+```
+
+[samples]: https://github.com/buildpack/samples