Skip to content

Commit ac4f0a5

Browse files
AidanDelaneyAidanDelaney
authored
Merge pull request cds-hooks#634 from buildpacks/fix/node-js-docs
Use named platform variables instead of positional args
2 parents 6e8bd44 + 0ed09d8 commit ac4f0a5

File tree

8 files changed

+62
-77
lines changed

8 files changed

+62
-77
lines changed

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ Before we get started, make sure you've got the following installed:
1717
## Overview
1818
<!--+end+-->
1919

20-
This is a step-by-step tutorial for creating a Ruby Cloud Native Buildpack.
20+
This is a step-by-step tutorial for creating a nodeJS Cloud Native Buildpack.
2121

2222
- [Set up your local environment](/docs/buildpack-author-guide/create-buildpack/setup-local-environment)
2323
- [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

Lines changed: 8 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@ Then, in our buildpack implementation we will generate the necessary SBOM metada
6666
# ...
6767

6868
# Append a Bill-of-Materials containing metadata about the provided node-js version
69-
cat >> "${layersdir}/node-js.sbom.cdx.json" << EOL
69+
cat >> "${CNB_LAYERS_DIR}/node-js.sbom.cdx.json" << EOL
7070
{
7171
"bomFormat": "CycloneDX",
7272
"specVersion": "1.4",
@@ -85,7 +85,7 @@ EOL
8585
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`:
8686

8787
```bash
88-
node-jsbom="${layersdir}/node-js.sbom.cdx.json"
88+
node-jsbom="${CNB_LAYERS_DIR}/node-js.sbom.cdx.json"
8989
cat >> ${node-jsbom} << EOL
9090
{
9191
"bomFormat": "CycloneDX",
@@ -113,18 +113,17 @@ echo "---> NodeJS Buildpack"
113113

114114
# ======= MODIFIED =======
115115
# 1. GET ARGS
116-
layersdir=$1
117-
plan=$3
116+
plan=${CNB_BP_PLAN_PATH}
118117

119118
# 2. CREATE THE LAYER DIRECTORY
120-
node_js_layer="${layersdir}"/node-js
119+
node_js_layer="${CNB_LAYERS_DIR}"/node-js
121120
mkdir -p "${node_js_layer}"
122121

123122
# 3. DOWNLOAD node-js
124123
default_node_js_version="18.18.1"
125124
node_js_version=$(cat "$plan" | yj -t | jq -r '.entries[] | select(.name == "node-js") | .metadata.version' || echo ${default_node_js_version})
126125
node_js_url=https://nodejs.org/dist/v${node_js_version}/node-v${node_js_version}-linux-x64.tar.xz
127-
remote_nodejs_version=$(cat "${layersdir}/node-js.toml" 2> /dev/null | yj -t | jq -r .metadata.nodejs_version 2>/dev/null || echo 'NOT FOUND')
126+
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')
128127
if [[ "${node_js_url}" != *"${remote_nodejs_version}"* ]] ; then
129128
echo "-----> Downloading and extracting NodeJS"
130129
wget -q -O - "${node_js_url}" | tar -xJf - --strip-components 1 -C "${node_js_layer}"
@@ -133,7 +132,7 @@ else
133132
fi
134133

135134
# 4. MAKE node-js AVAILABLE DURING LAUNCH and CACHE the LAYER
136-
cat > "${layersdir}/node-js.toml" << EOL
135+
cat > "${CNB_LAYERS_DIR}/node-js.toml" << EOL
137136
[types]
138137
cache = true
139138
launch = true
@@ -142,7 +141,7 @@ nodejs_version = "${node_js_version}"
142141
EOL
143142

144143
# 5. SET DEFAULT START COMMAND
145-
cat >> "${layersdir}/launch.toml" << EOL
144+
cat >> "${CNB_LAYERS_DIR}/launch.toml" << EOL
146145
[[processes]]
147146
type = "web"
148147
command = "node app.js"
@@ -151,7 +150,7 @@ EOL
151150

152151
# ========== ADDED ===========
153152
# 6. ADD A SBOM
154-
node_jsbom="${layersdir}/node-js.sbom.cdx.json"
153+
node_jsbom="${CNB_LAYERS_DIR}/node-js.sbom.cdx.json"
155154
cat >> ${node_jsbom} << EOL
156155
{
157156
"bomFormat": "CycloneDX",

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

Lines changed: 8 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ Let's begin by changing the `node-js-buildpack/bin/build`<!--+"{{open}}"+--> so
1616

1717
### Creating a Layer
1818

19-
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:
19+
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).
2020

2121
<!-- file=node-js-buildpack/bin/build -->
2222
```bash
@@ -25,9 +25,7 @@ set -eo pipefail
2525

2626
echo "---> NodeJS Buildpack"
2727

28-
layersdir=$1
29-
30-
node_js_layer="${layersdir}"/node-js
28+
node_js_layer="${CNB_LAYERS_DIR}"/node-js
3129
mkdir -p "${node_js_layer}"
3230
```
3331

@@ -48,7 +46,7 @@ The last step in creating a layer is writing a TOML file that contains metadata
4846

4947
<!-- file=node-js-buildpack/bin/build data-target=append -->
5048
```bash
51-
echo -e '[types]\nlaunch = true' > "${layersdir}/node-js.toml"
49+
echo -e '[types]\nlaunch = true' > "${CNB_LAYERS_DIR}/node-js.toml"
5250
```
5351

5452
Now the Buildpack is ready to test.
@@ -64,20 +62,17 @@ set -eo pipefail
6462

6563
echo "---> NodeJS Buildpack"
6664

67-
# 1. GET ARGS
68-
layersdir=$1
69-
70-
# 2. CREATE THE LAYER DIRECTORY
71-
node_js_layer="${layersdir}"/node-js
65+
# 1. CREATE THE LAYER DIRECTORY
66+
node_js_layer="${CNB_LAYERS_DIR}"/node-js
7267
mkdir -p "${node_js_layer}"
7368

74-
# 3. DOWNLOAD node-js
69+
# 2. DOWNLOAD node-js
7570
echo "---> Downloading and extracting NodeJS"
7671
node_js_url=https://nodejs.org/dist/v18.18.1/node-v18.18.1-linux-x64.tar.xz
7772
wget -q -O - "${node_js_url}" | tar -xJf - --strip-components 1 -C "${node_js_layer}"
7873

79-
# 4. MAKE node-js AVAILABLE DURING LAUNCH
80-
echo -e '[types]\nlaunch = true' > "${layersdir}/node-js.toml"
74+
# 3. MAKE node-js AVAILABLE DURING LAUNCH
75+
echo -e '[types]\nlaunch = true' > "${CNB_LAYERS_DIR}/node-js.toml"
8176
```
8277

8378
Build your app again:

‎content/docs/buildpack-author-guide/create-buildpack/caching.md

Lines changed: 21 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -13,14 +13,14 @@ To do this, replace the following lines in the `build` script:
1313

1414
```bash
1515
# 4. MAKE node-js AVAILABLE DURING LAUNCH
16-
echo -e '[types]\nlaunch = true' > "${layersdir}/node-js.toml"
16+
echo -e '[types]\nlaunch = true' > "${CNB_LAYERS_DIR}/node-js.toml"
1717
```
1818

1919
with the following:
2020

2121
```bash
2222
# 4. MAKE node-js AVAILABLE DURING LAUNCH and CACHE it
23-
echo -e '[types]\ncache = true\nlaunch = true' > "${layersdir}/node-js.toml"
23+
echo -e '[types]\ncache = true\nlaunch = true' > "${CNB_LAYERS_DIR}/node-js.toml"
2424
```
2525

2626
Your full `node-js-buildpack/bin/build`<!--+"{{open}}"+--> script should now look like the following:
@@ -32,24 +32,25 @@ set -eo pipefail
3232

3333
echo "---> NodeJS Buildpack"
3434

35-
# 1. GET ARGS
36-
layersdir=$1
37-
38-
# 2. CREATE THE LAYER DIRECTORY
39-
node_js_layer="${layersdir}"/node-js
35+
# 1. CREATE THE LAYER DIRECTORY
36+
node_js_layer="${CNB_LAYERS_DIR}"/node-js
4037
mkdir -p "${node_js_layer}"
4138

42-
# 3. DOWNLOAD NodeJS
39+
# 2. DOWNLOAD NodeJS
4340
echo "---> Downloading and extracting NodeJS"
4441
node_js_url=https://nodejs.org/dist/v18.18.1/node-v18.18.1-linux-x64.tar.xz
4542
wget -q -O - "$node_js_url" | tar -xJf - --strip-components 1 -C "${node_js_layer}"
4643

47-
# 4. MAKE NodeJS AVAILABLE DURING LAUNCH and CACHE the LAYER
44+
# 3. MAKE NodeJS AVAILABLE DURING LAUNCH and CACHE the LAYER
4845
# ========== MODIFIED ===========
49-
echo -e '[types]\ncache = true\nlaunch = true' > "${layersdir}/node-js.toml"
46+
cat > "${CNB_LAYERS_DIR}/node-js.toml" << EOL
47+
[types]
48+
cache = true
49+
launch = true
50+
EOL
5051

51-
# 5. SET DEFAULT START COMMAND
52-
cat > "${layersdir}/launch.toml" << EOL
52+
# 4. SET DEFAULT START COMMAND
53+
cat > "${CNB_LAYERS_DIR}/launch.toml" << EOL
5354
# our web process
5455
[[processes]]
5556
type = "web"
@@ -90,18 +91,15 @@ set -eo pipefail
9091
9192
echo "---> NodeJS Buildpack"
9293
93-
# 1. GET ARGS
94-
layersdir=$1
95-
96-
# 2. CREATE THE LAYER DIRECTORY
97-
node_js_layer="${layersdir}"/node-js
94+
# 1. CREATE THE LAYER DIRECTORY
95+
node_js_layer="${CNB_LAYERS_DIR}"/node-js
9896
mkdir -p "${node_js_layer}"
9997
10098
# ======= MODIFIED =======
101-
# 3. DOWNLOAD node-js
99+
# 2. DOWNLOAD node-js
102100
node_js_version="18.18.1"
103101
node_js_url=https://nodejs.org/dist/v${node_js_version}/node-v${node_js_version}-linux-x64.tar.xz
104-
cached_nodejs_version=$(cat "${layersdir}/node-js.toml" 2> /dev/null | yj -t | jq -r .metadata.nodejs_version 2>/dev/null || echo 'NOT FOUND')
102+
cached_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')
105103
if [[ "${node_js_url}" != *"${cached_nodejs_version}"* ]] ; then
106104
echo "-----> Downloading and extracting NodeJS"
107105
wget -q -O - "${node_js_url}" | tar -xJf - --strip-components 1 -C "${node_js_layer}"
@@ -110,17 +108,17 @@ else
110108
fi
111109
112110
# ======= MODIFIED =======
113-
# 4. MAKE node-js AVAILABLE DURING LAUNCH and CACHE the LAYER
114-
cat > "${layersdir}/node-js.toml" << EOL
111+
# 3. MAKE node-js AVAILABLE DURING LAUNCH and CACHE the LAYER
112+
cat > "${CNB_LAYERS_DIR}/node-js.toml" << EOL
115113
[types]
116114
cache = true
117115
launch = true
118116
[metadata]
119117
nodejs_version = "${node_js_version}"
120118
EOL
121119
122-
# 5. SET DEFAULT START COMMAND
123-
cat >> "${layersdir}/launch.toml" << EOL
120+
# 4. SET DEFAULT START COMMAND
121+
cat >> "${CNB_LAYERS_DIR}/launch.toml" << EOL
124122
[[processes]]
125123
type = "web"
126124
command = "node app.js"

‎content/docs/buildpack-author-guide/create-buildpack/make-app-runnable.md

Lines changed: 8 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ To make your app runnable, a default start command must be set. You'll need to a
1212
# ...
1313

1414
# Set default start command
15-
cat > "${layersdir}/launch.toml" << EOL
15+
cat > "${CNB_LAYERS_DIR}/launch.toml" << EOL
1616
[[processes]]
1717
type = "web"
1818
command = "node app.js"
@@ -31,24 +31,21 @@ set -eo pipefail
3131

3232
echo "---> NodeJS Buildpack"
3333

34-
# 1. GET ARGS
35-
layersdir=$1
36-
37-
# 2. CREATE THE LAYER DIRECTORY
38-
node_js_layer="${layersdir}"/node-js
34+
# 1. CREATE THE LAYER DIRECTORY
35+
node_js_layer="${CNB_LAYERS_DIR}"/node-js
3936
mkdir -p "${node_js_layer}"
4037

41-
# 3. DOWNLOAD node-js
38+
# 2. DOWNLOAD node-js
4239
echo "---> Downloading and extracting NodeJS"
4340
node_js_url=https://nodejs.org/dist/v18.18.1/node-v18.18.1-linux-x64.tar.xz
4441
wget -q -O - "$node_js_url" | tar -xJf - --strip-components 1 -C "${node_js_layer}"
4542

46-
# 4. MAKE node-js AVAILABLE DURING LAUNCH
47-
echo -e '[types]\nlaunch = true' > "${layersdir}/node-js.toml"
43+
# 3. MAKE node-js AVAILABLE DURING LAUNCH
44+
echo -e '[types]\nlaunch = true' > "${CNB_LAYERS_DIR}/node-js.toml"
4845

4946
# ========== ADDED ===========
50-
# 5. SET DEFAULT START COMMAND
51-
cat > "${layersdir}/launch.toml" << EOL
47+
# 4. SET DEFAULT START COMMAND
48+
cat > "${CNB_LAYERS_DIR}/launch.toml" << EOL
5249
[[processes]]
5350
type = "web"
5451
command = "node app.js"

‎content/docs/buildpack-author-guide/create-buildpack/make-buildpack-configurable.md

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ if [[ ! -f package.json ]]; then
2323
fi
2424

2525
# ======= ADDED =======
26-
plan=$2
26+
plan=${CNB_BUILD_PLAN_PATH}
2727
version=3.1.3
2828

2929
if [[ -f .node-js-version ]]; then
@@ -48,19 +48,18 @@ echo "---> NodeJS Buildpack"
4848

4949
# ======= MODIFIED =======
5050
# 1. GET ARGS
51-
layersdir=$1
52-
plan=$3
51+
plan=${CNB_BP_PLAN_PATH}
5352

5453
# 2. CREATE THE LAYER DIRECTORY
55-
node_js_layer="${layersdir}"/node-js
54+
node_js_layer="${CNB_LAYERS_DIR}"/node-js
5655
mkdir -p "${node_js_layer}"
5756

5857
# ======= MODIFIED =======
5958
# 3. DOWNLOAD node-js
6059
default_node_js_version="18.18.1"
6160
node_js_version=$(cat "$plan" | yj -t | jq -r '.entries[] | select(.name == "node-js") | .metadata.version' || echo ${default_node_js_version})
6261
node_js_url=https://nodejs.org/dist/v${node_js_version}/node-v${node_js_version}-linux-x64.tar.xz
63-
remote_nodejs_version=$(cat "${layersdir}/node-js.toml" 2> /dev/null | yj -t | jq -r .metadata.nodejs_version 2>/dev/null || echo 'NOT FOUND')
62+
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')
6463
if [[ "${node_js_url}" != *"${remote_nodejs_version}"* ]] ; then
6564
echo "-----> Downloading and extracting NodeJS" ${node_js_version}
6665
wget -q -O - "${node_js_url}" | tar -xJf - --strip-components 1 -C "${node_js_layer}"
@@ -69,7 +68,7 @@ else
6968
fi
7069

7170
# 4. MAKE node-js AVAILABLE DURING LAUNCH and CACHE the LAYER
72-
cat > "${layersdir}/node-js.toml" << EOL
71+
cat > "${CNB_LAYERS_DIR}/node-js.toml" << EOL
7372
[types]
7473
cache = true
7574
launch = true
@@ -79,7 +78,7 @@ EOL
7978

8079
# ========== ADDED ===========
8180
# 5. SET DEFAULT START COMMAND
82-
cat >> "${layersdir}/launch.toml" << EOL
81+
cat >> "${CNB_LAYERS_DIR}/launch.toml" << EOL
8382
[[processes]]
8483
type = "web"
8584
command = "node app.js"

‎content/docs/buildpack-author-guide/create-buildpack/setup-local-environment.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ docker rmi test-node-js-app
2020
```
2121
-->
2222

23-
First, we'll create a sample Ruby app that you can use when developing your buildpack:
23+
First, we'll create a sample nodeJS app that you can use when developing your buildpack:
2424

2525
<!-- test:exec -->
2626
```bash

‎content/docs/buildpack-author-guide/create-buildpack/specify-multiple-process-types.md

Lines changed: 9 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ To enable running the debug process, we'll need to have our buildpack define a "
1212
```bash
1313
# ...
1414

15-
cat > "${layersdir}/launch.toml" << EOL
15+
cat > "${CNB_LAYERS_DIR}/launch.toml" << EOL
1616
# our web process
1717
[[processes]]
1818
type = "web"
@@ -21,7 +21,7 @@ default = true
2121
2222
# our debug process
2323
[[processes]]
24-
type = "debug"
24+
type = "worker"
2525
command = "node --inspect app.js"
2626
EOL
2727

@@ -37,27 +37,24 @@ set -eo pipefail
3737

3838
echo "---> NodeJS Buildpack"
3939

40-
# 1. GET ARGS
41-
layersdir=$1
42-
43-
# 2. CREATE THE LAYER DIRECTORY
44-
node_js_layer="${layersdir}"/node-js
40+
# 1. CREATE THE LAYER DIRECTORY
41+
node_js_layer="${CNB_LAYERS_DIR}"/node-js
4542
mkdir -p "${node_js_layer}"
4643

47-
# 3. DOWNLOAD node-js
44+
# 2. DOWNLOAD node-js
4845
echo "---> Downloading and extracting NodeJS"
4946
node_js_url=https://nodejs.org/dist/v18.18.1/node-v18.18.1-linux-x64.tar.xz
5047
wget -q -O - "$node_js_url" | tar -xJf - --strip-components 1 -C "${node_js_layer}"
5148

52-
# 4. MAKE node-js AVAILABLE DURING LAUNCH
53-
cat > "${layersdir}/node-js.toml" << EOL
49+
# 3. MAKE node-js AVAILABLE DURING LAUNCH
50+
cat > "${CNB_LAYERS_DIR}/node-js.toml" << EOL
5451
[types]
5552
launch = true
5653
EOL
5754

5855
# ========== MODIFIED ===========
59-
# 5. SET DEFAULT START COMMAND
60-
cat > "${layersdir}/launch.toml" << EOL
56+
# 4. SET DEFAULT START COMMAND
57+
cat > "${CNB_LAYERS_DIR}/launch.toml" << EOL
6158
# our web process
6259
[[processes]]
6360
type = "web"

0 commit comments

Comments
 (0)