[WIP] Restructure App Developer Guide

Makefile

@@ -175,17 +175,3 @@ prepare-for-pr: check-links test tools-tidy katacoda
 	@echo "It looks good! :)"
 	@echo "Make sure to commit all changes!"
 	@echo "========"
-
-.PHONY: katacoda
-katacoda:
-	@echo "========"
-	@echo "Generating Katacoda docs..."
-	@go run katacoda/main.go
-	@echo "All done!"
-	@echo "========"
-
-.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)
-	@echo "All katacoda docs are up-to-date"

content/docs/app-developer-guide/_index.md

@@ -1,6 +1,6 @@
 +++
-title="App Developer Guide"
-weight=4
+title="For App Developers"
+weight=1
 include_summaries=true
 expand=true
 +++

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

@@ -10,8 +10,32 @@ aliases=[
 # Build an app
 `+-->
 
+<!-- test:suite=create-app;weight=1 -->
+
+<!-- test:setup:exec;exit-code=-1 -->
+<!--
+```bash
+docker rmi sample-app
+pack config trusted-builders add cnbs/sample-builder:jammy
+```
+-->
+
+<!-- test:teardown:exec -->
+<!--
+```bash
+docker rmi sample-app
+```
+-->
+
 Building an app using Cloud Native Buildpacks is as easy as `1`, `2`, `3`...
 
+## Prerequisites
+
+A lot of the examples used within this guide will require the following: 
+
+{{< download-button href="https://store.docker.com/search?type=edition&offering=community" color="blue" >}} Install Docker {{</>}}
+{{< download-button href="/docs/install-pack" color="pink" >}} Install pack {{</>}}
+
 ### 1. Select a builder
 
 To [build][build] an app you must first decide which [builder][builder] you're going to use. A builder
@@ -28,18 +52,22 @@ pack builder suggest
 For this guide we're actually going to use a sample builder, `cnbs/sample-builder:jammy`, which is not listed
 as a suggested builder for good reason. It's a sample.
 
+> **TIP:**  If you want to try production grade buildpacks, instead of our sample, use the `paketobuildpacks/builder:full` builder.  Alternatively, if you intend to deploy your application on Google Cloud Run, use try the `Google` builder.  If your intended platform is Heroku, use the `Heroku` builder.
+
 ### 2. Build your app
 
 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.
 
 1. Check that the samples repo exists and if not - we clone it
+<!-- test:exec -->
 ```
 ls samples || git clone https://github.com/buildpacks/samples
 ```
 <!--+- "{{execute}}"+-->
 
 2. Build the app
+<!-- test:exec -->
 ```
 pack build sample-app --path samples/apps/java-maven --builder cnbs/sample-builder:jammy
 ```
@@ -51,8 +79,11 @@ pack build sample-app --path samples/apps/java-maven --builder cnbs/sample-build
 
 ### 3. Run it
 
+Here we `--name` the running container so that we can clean up after it:
+
+<!-- test:exec -->
 ```
-docker run --rm -p 8080:8080 sample-app
+docker run --rm -p 8080:8080 --name sample-app sample-app
 ```
 <!--+- "{{execute}}"+-->
 
@@ -62,18 +93,36 @@ docker run --rm -p 8080:8080 sample-app
 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)
-` +-->
+### 4. Verify it
+
+Executing
+
+<!-- test:exec -->
+```
+curl http://localhost:8080
+```
+
+should contain the `<title>`
+<!-- test:assert=contains -->
+```text
+Buildpacks.io Java Sample
+```
+
+### 5. Clean it up
+
+<!-- test:exec -->
+```
+docker kill sample-app
+```
 
 ## 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>
+<a href="/docs/app-developer-guide/how-to/build-an-arm-app" class="button bg-blue">Linux ARM build guide</a>
 <!--+end+-->
 
 <!--+ `
@@ -84,7 +133,7 @@ Check out the [Linux ARM build guide](https://buildpacks.io//docs/app-developer-
 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>
+<a href="/docs/app-developer-guide/how-to/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/).

content/docs/concepts/_index.md → content/docs/app-developer-guide/concepts/_index.md

@@ -1,6 +1,6 @@
 +++
 title="Concepts"
-weight=3
+weight=1000
 expand=false
 +++
 

content/docs/app-developer-guide/how-to/_index.md

@@ -0,0 +1,5 @@
++++
+title="How To"
+weight=100
+summary="Short focused guides to performing a specific task"
++++

content/docs/app-developer-guide/building-on-podman.md → content/docs/app-developer-guide/how-to/building-on-podman.md

@@ -1,6 +1,6 @@
 +++
-title="Building on Podman"
-weight=99
+title="(Advanced) Building on Podman"
+weight=20
 summary="Use podman as an alternative to Docker with Cloud Native Buildpacks."
 aliases=[
     "/docs/using-pack/building-app/"

content/docs/app-developer-guide/environment-variables.md → content/docs/app-developer-guide/how-to/using-environment-variables.md

@@ -1,6 +1,6 @@
 +++
 title="Environment variables"
-weight=3
+weight=2
 summary="Environment variables are a common way to configure various buildpacks at build-time."
 +++
 <!--+- `

content/docs/app-developer-guide/tutorials/_index.md

@@ -0,0 +1,5 @@
++++
+title="Tutorials"
+weight=200
+summary="Introductory articles that describe details"
++++

content/docs/app-developer-guide/build-a-windows-app.md → content/docs/app-developer-guide/tutorials/build-a-windows-app.md

@@ -1,6 +1,6 @@
 +++
-title="Build a Windows app"
-weight=2
+title="(Advanced) Build a Windows app"
+weight=20
 summary="The basics of taking your Windows app from source code to runnable image."
 +++
 

content/docs/app-developer-guide/build-an-arm-app.md → content/docs/app-developer-guide/tutorials/build-an-arm-app.md

@@ -1,6 +1,6 @@
 +++
-title="Build an ARM app"
-weight=2
+title="(Advanced) Build an ARM app"
+weight=20
 summary="The basics of taking your app from source code to runnable ARM image."
 +++
 

content/docs/buildpack-author-guide/_index.md

@@ -1,5 +1,5 @@
 +++
-title="Buildpack Author Guide"
+title="For Buildpack Authors"
 weight=4
 include_summaries=true
 expand=true

content/docs/buildpack-author-guide/create-buildpack/_index.md

@@ -17,7 +17,7 @@ Before we get started, make sure you've got the following installed:
 ## Overview
 <!--+end+-->
 
-This is a step-by-step tutorial for creating a Ruby Cloud Native Buildpack.
+This is a step-by-step tutorial for creating a nodeJS Cloud Native Buildpack.
 
 - [Set up your local environment](/docs/buildpack-author-guide/create-buildpack/setup-local-environment)
 - [Building blocks of a Cloud Native Buildpack](/docs/buildpack-author-guide/create-buildpack/building-blocks-cnb)

content/docs/buildpack-author-guide/create-buildpack/adding-bill-of-materials.md

@@ -66,7 +66,7 @@ Then, in our buildpack implementation we will generate the necessary SBOM metada
 # ...
 
 # Append a Bill-of-Materials containing metadata about the provided node-js version
-cat >> "${layersdir}/node-js.sbom.cdx.json" << EOL
+cat >> "${CNB_LAYERS_DIR}/node-js.sbom.cdx.json" << EOL
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.4",
@@ -85,7 +85,7 @@ EOL
 We can also add an SBOM entry for each dependency listed in `package.json`.  Here we use `jq` to add a new record to the `components` array in `bundler.sbom.cdx.json`:
 
 ```bash
-node-jsbom="${layersdir}/node-js.sbom.cdx.json"
+node-jsbom="${CNB_LAYERS_DIR}/node-js.sbom.cdx.json"
 cat >> ${node-jsbom} << EOL
 {
   "bomFormat": "CycloneDX",
@@ -113,18 +113,17 @@ echo "---> NodeJS Buildpack"
 
 # ======= MODIFIED =======
 # 1. GET ARGS
-layersdir=$1
-plan=$3
+plan=${CNB_BP_PLAN_PATH}
 
 # 2. CREATE THE LAYER DIRECTORY
-node_js_layer="${layersdir}"/node-js
+node_js_layer="${CNB_LAYERS_DIR}"/node-js
 mkdir -p "${node_js_layer}"
 
 # 3. DOWNLOAD node-js
 default_node_js_version="18.18.1"
 node_js_version=$(cat "$plan" | yj -t | jq -r '.entries[] | select(.name == "node-js") | .metadata.version' || echo ${default_node_js_version})
 node_js_url=https://nodejs.org/dist/v${node_js_version}/node-v${node_js_version}-linux-x64.tar.xz
-remote_nodejs_version=$(cat "${layersdir}/node-js.toml" 2> /dev/null | yj -t | jq -r .metadata.nodejs_version 2>/dev/null || echo 'NOT FOUND')
+remote_nodejs_version=$(cat "${CNB_LAYERS_DIR}/node-js.toml" 2> /dev/null | yj -t | jq -r .metadata.nodejs_version 2>/dev/null || echo 'NOT FOUND')
 if [[ "${node_js_url}" != *"${remote_nodejs_version}"* ]] ; then
     echo "-----> Downloading and extracting NodeJS"
     wget -q -O - "${node_js_url}" | tar -xJf - --strip-components 1 -C "${node_js_layer}"
@@ -133,7 +132,7 @@ else
 fi
 
 # 4. MAKE node-js AVAILABLE DURING LAUNCH and CACHE the LAYER
-    cat > "${layersdir}/node-js.toml" << EOL
+    cat > "${CNB_LAYERS_DIR}/node-js.toml" << EOL
 [types]
 cache = true
 launch = true
@@ -142,7 +141,7 @@ nodejs_version = "${node_js_version}"
 EOL
 
 # 5. SET DEFAULT START COMMAND
-cat >> "${layersdir}/launch.toml" << EOL
+cat >> "${CNB_LAYERS_DIR}/launch.toml" << EOL
 [[processes]]
 type = "web"
 command = "node app.js"
@@ -151,7 +150,7 @@ EOL
 
 # ========== ADDED ===========
 # 6. ADD A SBOM
-node_jsbom="${layersdir}/node-js.sbom.cdx.json"
+node_jsbom="${CNB_LAYERS_DIR}/node-js.sbom.cdx.json"
 cat >> ${node_jsbom} << EOL
 {
   "bomFormat": "CycloneDX",

content/docs/buildpack-author-guide/create-buildpack/build-app.md

@@ -16,7 +16,7 @@ Let's begin by changing the `node-js-buildpack/bin/build`<!--+"{{open}}"+--> so
 
 ### Creating a Layer
 
-A Buildpack layer is represented by a directory inside the [layers directory][layers-dir] provided to our buildpack by the Buildpack execution environment.  As defined by the buildpack specification, the layers directory is always passed to the `build` script as the first positional parameter. To create a new layer directory representing the NodeJS runtime, change the `build` script to look like this:
+A Buildpack layer is represented by a directory inside the [layers directory][layers-dir] provided to our buildpack by the Buildpack execution environment.  As defined by the buildpack specification, the layers directory is always passed to the `build` script as the first positional parameter. To create a new layer directory representing the NodeJS runtime, change the `build` script to look like the following.  The variable `CNB_LAYERS_DIR` is provided to the build script as defined by the [buildpacks specification](https://github.com/buildpacks/spec/blob/main/buildpack.md#positional-arguments-to-detect-and-build-executables).
 
 <!-- file=node-js-buildpack/bin/build -->
 ```bash
@@ -25,9 +25,7 @@ set -eo pipefail
 
 echo "---> NodeJS Buildpack"
 
-layersdir=$1
-
-node_js_layer="${layersdir}"/node-js
+node_js_layer="${CNB_LAYERS_DIR}"/node-js
 mkdir -p "${node_js_layer}"
 ```
 
@@ -48,7 +46,7 @@ The last step in creating a layer is writing a TOML file that contains metadata
 
 <!-- file=node-js-buildpack/bin/build data-target=append -->
 ```bash
-echo -e '[types]\nlaunch = true' > "${layersdir}/node-js.toml"
+echo -e '[types]\nlaunch = true' > "${CNB_LAYERS_DIR}/node-js.toml"
 ```
 
 Now the Buildpack is ready to test.
@@ -64,20 +62,17 @@ set -eo pipefail
 
 echo "---> NodeJS Buildpack"
 
-# 1. GET ARGS
-layersdir=$1
-
-# 2. CREATE THE LAYER DIRECTORY
-node_js_layer="${layersdir}"/node-js
+# 1. CREATE THE LAYER DIRECTORY
+node_js_layer="${CNB_LAYERS_DIR}"/node-js
 mkdir -p "${node_js_layer}"
 
-# 3. DOWNLOAD node-js
+# 2. DOWNLOAD node-js
 echo "---> Downloading and extracting NodeJS"
 node_js_url=https://nodejs.org/dist/v18.18.1/node-v18.18.1-linux-x64.tar.xz
 wget -q -O - "${node_js_url}" | tar -xJf - --strip-components 1 -C "${node_js_layer}"
 
-# 4. MAKE node-js AVAILABLE DURING LAUNCH
-echo -e '[types]\nlaunch = true' > "${layersdir}/node-js.toml"
+# 3. MAKE node-js AVAILABLE DURING LAUNCH
+echo -e '[types]\nlaunch = true' > "${CNB_LAYERS_DIR}/node-js.toml"
 ```
 
 Build your app again: