buildpacks / docs

Web content for Cloud Native Buildpacks

Docs for Cloud Native Buildpacks

Preview

Management

Calendar

The calendar is managed via teamup. To request an alteration you may create an issue, reach out to a maintainer via slack in #buildpacks-maintainers, post in discussions.

Contributing

We ❤ contributions.

To learn more, read the CONTRIBUTING, RELEASE and DEVELOPMENT documents.

docs's Issues

missing `pack` binaries for Linux

On Page: Installing pack

The install command for Linux does not work:

wget https://github.com/buildpacks/pack/releases/download/vnull/pack-vnull-linux.tgz
--2019-12-13 02:17:24--  https://github.com/buildpacks/pack/releases/download/vnull/pack-vnull-linux.tgz
Resolving github.com (github.com)... 140.82.118.4
Connecting to github.com (github.com)|140.82.118.4|:443... connected.
HTTP request sent, awaiting response... 404 Not Found
2019-12-13 02:17:24 ERROR 404: Not Found.

Document --network flag

Document --network flag based on functionality and potential use cases.

See buildpacks/pack#328 and buildpacks/pack#309 for history and additional information.

Document mixins

Document mixins and current state of validation.

Create PR on branch release/0.6.0

Suggestion: Tutorial to use https for git URL?

I found the tutorial's git clone code did not work for my environment. I feel it's simpler to use https URL like below.
https://buildpacks.io/docs/app-journey/

suztomo@suxtomo24:~/pack/app-journey$ git clone [email protected]:buildpack/sample-java-app.git
Cloning into 'sample-java-app'...
Warning: Permanently added the RSA host key for IP address '140.82.114.4' to the list of known hosts.
[email protected]: Permission denied (publickey).
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

With https URL:

suztomo@suxtomo24:~/pack/app-journey$ git clone https://github.com/buildpack/sample-java-app.git
Cloning into 'sample-java-app'...
remote: Enumerating objects: 62, done.
remote: Counting objects: 100% (62/62), done.
remote: Compressing objects: 100% (41/41), done.
remote: Total 62 (delta 8), reused 53 (delta 6), pack-reused 0
Receiving objects: 100% (62/62), 65.67 KiB | 5.97 MiB/s, done.
Resolving deltas: 100% (8/8), done.

What do you think?

Add reference documention

To make it easier for buildpack authors to create buildpacks, we should add a reference section that describes the interface for each buildpack script (in less formal language, compared to the spec).

Test Issue

"pack build" didn't just work

Following along at https://buildpacks.io/docs/create-buildpack/building-blocks-cnb/

I ran pack build but it didn't just build as explained in docs.

$ pack build test-ruby-app --buildpack ~/workspace/ruby-cnb  --path ~/workspace/ruby-sample-app/
Please select a default builder with:

	pack set-default-builder <builder image>

Suggested builders:

	Heroku:            heroku/buildpacks               heroku-18 base image with official Heroku buildpacks
	Cloud Foundry:     cloudfoundry/cnb:bionic         Small base image with Java & Node.js
	Cloud Foundry:     cloudfoundry/cnb:cflinuxfs3     Larger base image with Java, Node.js & Python

Tip: Learn more about a specific builder with:

	pack inspect-builder [builder image]

I needed to:

$ pack set-default-builder cloudfoundry/cnb:cflinuxfs3
Verifying local image...
Verifying remote image...
Builder cloudfoundry/cnb:cflinuxfs3 is now the default builder

Now pack build does something:

$ pack build test-ruby-app --buildpack ~/workspace/ruby-cnb  --path ~/workspace/ruby-sample-app/
Using default builder image cloudfoundry/cnb:cflinuxfs3
Pulling image index.docker.io/cloudfoundry/cnb:cflinuxfs3
cflinuxfs3: Pulling from cloudfoundry/cnb
01deb0c2b979: Downloading [===============>                                   ]  113.4MB/354.9MB
38a076a74898: Download complete
1731fd070804: Download complete
0d488abda820: Download complete
...

Sample app image from Environment variables page not runnable

On Page: Environment variables

The app created here isn't a runnable image. Logs:

$ docker run --rm -p 8080:8080 sample-app`
ERROR: failed to launch: determine start command: process type web was not found

The hello-world sample buildpack doesn't write a start command, and as such, isn't runnable.

This issue was raised here on the buildpacks slack

Feature request: Header links

We should have an easy way to copy/paste links to specific headers in docs, as is common in other documentation sites

Look into github actions for generating docs, rather than putting generated content under VCS

Tutorial refers to 3 stacks while the example only shows 2

This section of the tutorial defines two stacks, followed by this sentence:

This example can be run on one of three different stacks, all based upon Ubuntu Bionic.

It looks like either a stack in the example is missing or that sentence should be updated.

Document reproducible builds

Summary

Create a page to document reproducible builds.

Some questions that this document should answer:

• What constitutes as a reproducible build?
• What caveats are there, if any?

Considerations

• What persona cares most about this?
• Where should it live within buildpacks.io?
• The CNB lifecycle implementation is only one implementation of the spec so this document should call out that it only applies to the CNB lifecycle and is not necessarily spec'd.

Notes

• Relates to:
  • Slack conversation: https://buildpacks.slack.com/archives/C94UJCNV6/p1580223671047400
  • buildpacks/lifecycle#226

Failed to fetch builder image: <empty transport.Error response>

On Page: An App's Brief Journey from Source to Image

The referenced build docker image cnbs/sample-builder does not exist on hub.docker.com

Idea: an "edit" and "create issue" button/link on each page

I don't think I can see an "edit this page" or "ask question about this page" link on the site. This might be a good idea to foster small PRs + to gather questions.

Technical overview documentation

It would be helpful for the broader community to have access to some of the decks from conference presentations, etc, in addition to the videos that are already accessible. For now, a PDF would be great, but eventually some could make their way into becoming actual web pages.

wget: command not found with builder `cloudfoundry/cnb:bionic`

On Page: Building your application

With the default builder cloudfoundry/cnb:bionic selected the following error occurs when running the build:

===> BUILDING
[builder] ---> Java Buildpack
[builder] ---> Downloading and extracting OpenJDK
[builder] /cnb/buildpacks/io.github.derkoe.buildpacks.java/0.0.1/bin/build: line 14: wget: command not found
[builder]
[builder] gzip: stdin: unexpected end of file
[builder] tar: Child returned status 1
[builder] tar: Error is not recoverable: exiting now
[builder] Error: failed to build: exit status 2

The step works when selecting cloudfoundry/cnb:cflinuxfs3 as default builder

Make serve does not reflect what will build

I submitted a PR and previewed it on my local machine, using make serve. The results looked good. However when that PR was merged, the doc site looked pretty different from what I expected.

expected:

actual:

Docs spruce up

Our docs are in general looking a little 🕸 dusty and could use some love.

Specifically:
#113
#14
#111
#105

Update Buildpack Author's Guide to API v3

The "Building blocks of a Cloud Native Buildpack" section of the Buildpack Author's Guide uses the v2 Buildpack API.

Update the guide to use the v3 API.

Document build plan

We need to better explain and document the format of build plan. Particularly, the provides and requires concepts.

References: https://github.com/buildpack/spec/blob/master/buildpack.md#build-plan-toml

This should entail:

• Explaining it as part of the tutorial
• Adding it to the buildpack API reference

Document pack cli commands

In order to make documentation of the behavior of pack more discoverable (and so that we can more easily point to it), it would be nice if pack's commands were documented. This could start as a folder in pack proper that we create during releases and then move here somehow.

Cobra supports this (POC).

Document the requirements of a stack

Requirements:

Labels:

• io.buildpacks.stack.metadata OR io.buildpacks.stack.id

Env Vars:

• CNB_USER_ID
• CNB_GROUP_ID
• CNB_STACK_ID

Implementation Suggestions:

• Add a new sections to the docs website
• Link from the buildpack/stacks repo

Create a page to list of suggest builders

It would be nice to have a place to reference what builders are "suggested". For example, in documentation or various implementations where the configuration of builders is necessary we can point the user to a list of builders to use.

One example is the tekton task: https://github.com/tektoncd/catalog/tree/master/buildpacks

Notes:

• Consider having a central catalog of suggested builders and stacks that both the docs and pack read from.

Pack version is out of date

The slug doesn't seem to get updated when new releases of pack come out. I think it would be easier to just point to the brew tap and https://github.com/buildpacks/pack/releases/latest where necessary and leave out specific versions entirely

Windows ZIP file is not downloading the pack.exe file

https://github.com/buildpack/pack/releases/download/v0.5.0/pack-v0.5.0-windows.zip

On Page: Installing pack

Idea: add navigation between pages of tutorials

At the end of a page of the tutorials, e.g. https://buildpacks.io/docs/create-buildpack/building-blocks-cnb/, there is no "Next" button. Instead I scroll up, find the page I'm on on the left sidebar, and click on the next one. Perhaps a "Next" button might be nice.

More explanation of sections in buildpack.toml

Based on this issue about adding buildpack API to the docs (#66), it may be helpful to have more documentation for the buildpack.toml for each section (ie. id, stack, metadata, etc).

Looking here at buildpack.toml section: https://buildpacks.io/docs/reference/buildpack-api/

Document Governance

Document our Governance and team structure that was decided during the last CNB Summit.

Docs say latest version is 0.2.1

https://buildpacks.io/docs/install-pack/

I see 0.3.0 in https://github.com/buildpack/pack/releases

Document launch process

As an app developer, I would like to know all the ways in which I can interact with an image created with Cloud Native Buildpacks.

Some use cases:

• Pass arguments to a direct process type
• Execute arbitrary commands
• Selecting process type

Relates to buildpacks/lifecycle#280

Update creating a buildpack tutorial

edge docs still mention old plan.toml system (pass via STDIN into bin/build); the schema of bin/detect's plan.toml would not support this example; and bin/build consumes the plan.toml via $3 now.
https://github.com/buildpack/docs/blob/edge/content/docs/create-buildpack/caching.md

Originally posted by @drnic in #47 (comment)

The linked Ruby version with the installed version of bundler does not work

Issue

In the "creating a buildpack" tutorial at the build step(https://buildpacks.io/docs/create-buildpack/build-app/), the Ruby version that is used will error when just running gem install bundler and then bundle install. The user is told to run bundle update --bundler.

What I expect

I would expect that after install bundler of an unspecified version, bundle install would run without errors.

Possible Solutions

1. Update the Ruby version to 2.6.4 in the docs and remove the installation of bundler since it's included in that release.
2. Add the bundle update --bundler step to the docs.

Create Buildpack docs unclear/command doesn't work

I should have read the docs more carefully, sorry. My mistake. :)

wget missing from image used as builder for example ruby app

On Page: Building your application

bionic: Pulling from cloudfoundry/cnb
Digest: sha256:4acb6bfd6c4f0cabaf7f3690e444afe51f1c7de54d51da7e63fac709c56f1c30
Status: Image is up to date for cloudfoundry/cnb:bionic
base-cnb: Pulling from cloudfoundry/run
Digest: sha256:bd9df33bff1644d567a8f74b40b2f73246325b665ae9beeef3bea7e7fa2dd3ff
Status: Image is up to date for cloudfoundry/run:base-cnb
===> DETECTING
[detector] com.examples.buildpacks.ruby 0.0.1
===> RESTORING
[restorer] Cache '/cache': metadata not found, nothing to restore
===> ANALYZING
[analyzer] Warning: Image 'index.docker.io/library/test-ruby-app:latest' not found
===> BUILDING
[builder] ---> Ruby Buildpack
[builder] ---> Downloading and extracting Ruby
[builder] /cnb/buildpacks/com.examples.buildpacks.ruby/0.0.1/bin/build: line 14: wget: command not found```

Document Buildpack API Version

Request based on buildpacks/pack#306

It should probably live here: https://buildpacks.io/docs/reference/buildpack-api/

Reference: https://github.com/buildpack/spec/pull/61/files

Add adopters to home page

Based on conversations in the working group meeting, we've agreed to add a showcase of consumers of Cloud Native Buildpacks to our home page.

• Compile list of consumers - See adopters
• Propose design - "what is it going to look like?"

cloudfoundry/cnb:cflinuxfs3 builder has silent dependency on gcloud

On Page: Building blocks of a Cloud Native Buildpack

When attempting to use the cloudfoundry/cnb:cflinuxfs3 builder for the test ruby app, it failed out because ERROR: invalid run-image 'gcr.io/paketo-buildpacks/run:full-cnb-cf': error getting credentials - err: exec: "docker-credential-gcloud": executable file not found in $PATH, out: ``

It seems that cloudfoundry/cnb:cflinuxfs3 has a silent dependency on gcloud being in the path. Should that be explicitly noted?

The full logs are:

$  pack build ruby-app -p ruby-sample-app/ --buildpack temp-ruby-cnb/
cflinuxfs3: Pulling from cloudfoundry/cnb
7f9bce95fa3f: Pull complete
...
89732bc75041: Pull complete
Digest: sha256:13202cf555bfc209c7cd2f35fb35e5557b1410ab99623e656fa74a23f560755a
Status: Downloaded newer image for cloudfoundry/cnb:cflinuxfs3
ERROR: invalid run-image 'gcr.io/paketo-buildpacks/run:full-cnb-cf': error getting credentials - err: exec: "docker-credential-gcloud": executable file not found in $PATH, out: ``

Add Windows installation instructions

Installation instructions have recently been added for macOS and Linux but Windows instructions are still missing and consist only of a URL for a ZIP file.

Update docs with new toml changes from rfc#11 and rfc#12

Add some documentation for contributing to this repository

It might be useful to have some docs for contributing to the documentation.

Perhaps something like the following in README.md

Development

This documentation is build using hugo, install it using the guide here

git clone https://github.com/buildpack/docs.git
cd src
hugo server
# documentation is available at localhost:1313

Update latest pack version to not include drafts

Release 0.4.0 docs

Merge edge into master

Add mailing list to footer of site

Add the following Mailing List to the footer:

Document buildpackages

• pack package-buildpack
• pack create-builder (esp. builder.toml) and how to reference buildpackages
• pack build --buildpack <BUILDPACKAGE>

ERROR: processing order: no versions of buildpack io.buildpacks.samples.hello-world were found on the builder

On Page: Create a builder

I executed the command as suggested pack create-builder my-builder:bionic --builder-config ./builder.toml and pack is reporting the following error

bionic: Pulling from cnbs/sample-stack-build
Digest: sha256:bf945248e8add4ad2bd375463bdbc16d2214afa39dd397bb3359acc60119ffce
Status: Image is up to date for cnbs/sample-stack-build:bionic
hello-universe: Pulling from cnbs/sample-package
f88cb176274b: Pull complete
0c93e87ede7b: Pull complete
683a16f12fa8: Pull complete
Digest: sha256:a3dc49636f0dabd481906d1ee52c96e7daace1dea8b029c9ac36c27abe4cb1f6
Status: Downloaded newer image for cnbs/sample-package:hello-universe
ERROR: processing order: no versions of buildpack io.buildpacks.samples.hello-world were found on the builder

Can we rebuild the docs when a new version of pack is released?

I ran into #113 which, at the root of it, seems related to the fact that we're not currently "rebuilding" our docs when a new version of pack is released. In general our docs should, if possible, reflect the current command set, etc. so it would be neat if we could find a way to accomplish this.

Github actions?

Direct contributors (filing issues) to slack as a first line of defense

Based on an interview with a new contributor, it might be nice to have a note in the issue template or a bot that directs people to our slack instance as a first line of support (or in addition; having a record of the issue is good)

Pack version is missing from docs

At least on https://buildpacks.io/docs/install-pack/ we depend on knowing the latest pack version. We retrieve this data at build time from github directly. If an error occurs retrieving it we get a blank version on the docs and a broken link to Windows zip file.

Noticed that build logs contained the following error.

PACK_VERSION=$(curl -s https://api.github.com/repos/buildpack/pack/releases | jq -r '.[0].tag_name' | sed -e 's/^v//') hugo
jq: error (at <stdin>:4): Cannot index object with number

A couple things to consider:

1. We should fail the build when PACK_VERSION is not provided or resolved.
2. We should use a GITHUB_TOKEN to prevent rate limiting.

create-buildpack/caching - bin/build fails if Gemfile.lock missing

The script in https://buildpacks.io/docs/create-buildpack/caching/ looks like it should work if Gemfile.lock is missing; but it fails at the sha256sum Gemfile.lock line.

If Gemfile.lock is required, then we can remove the if [[ -f Gemfile.lock test in the script.

In the tutorial sequence, we never ran bundle install locally, so there is no Gemfile.lock locally; so anyone mindlessly following along will get an error at this point in the tutorial. Since someone following along might not have ruby/bundler installed locally, I think its ok to not require Gemfile.lock.

Example in "An App’s Brief Journey" doesn't work

Hi I just installed pack and tried to follow the "An App’s Brief Journey from Source to Image" example but it fails:

$ pwd
/Users/asd/Code/samples/apps/java-maven

$ pack build myapp --builder cnbs/sample-builder:bionic
bionic: Pulling from cnbs/sample-builder
Digest: sha256:85cb879dfcbcbd97425f3b8b92278f5049d721f31a026695e6f442b31c9a4fb7
Status: Image is up to date for cnbs/sample-builder:bionic
bionic: Pulling from cnbs/sample-stack-run
Digest: sha256:41609c85c96a36136d6af84294177f0390fadcae2200671d9d705a8cb61f21a3
Status: Image is up to date for cnbs/sample-stack-run:bionic
===> DETECTING
[detector] io.buildpacks.samples.java-maven 0.0.1
===> ANALYZING
[analyzer] Warning: Image "index.docker.io/library/myapp:latest" not found
===> RESTORING
===> BUILDING
[builder] ---> Java buildpack
[builder] ---> Installing JDK
[builder] 
[builder] gzip: stdin: unexpected end of file
[builder] tar: Child returned status 1
[builder] tar: Error is not recoverable: exiting now
[builder] ERROR: failed to build: exit status 2
ERROR: failed with status code: 7

$ pack --version
0.10.0+git-06d9983.build-259
$ docker --version
Docker version 19.03.8, build afacb8b

What am I doing wrong? (The bash example in the app directory works fine)