Skip to content
Open
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion content/docs/app-journey.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
+++
title="An App's Brief Journey from Source to Image"
weight=2
weight=3
getting-started=true
+++

Expand Down
63 changes: 63 additions & 0 deletions content/docs/buildpack-basics.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
+++
title="Basics of BuildPacks"
weight=2
getting-started=true
+++

## Basic Concepts

### What is a Buildpack?

A `buildpack` is software that transforms application source code into
executable files by analyzing the code and determining the best way to
build it.
Comment on lines +11 to +13
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've always found it difficult to describe what an individual buildpack is! A buildpack is a small software component that does something. Would we be better off here to explain by example? i.e. provide an example of a "distribution" buildpack, an a "build process" buildpack?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • How about adding the following paragraph under this definition:

Buildpacks have many shapes and forms. For example, a 'Distribution BuildPack' is a pre-built and tested buildpack that is ready for distribution to application developers. A Distribution Buildpack includes a set of buildpacks that are packaged together and can be used to build applications in different environments.

'Paketo Buildpacks' is a distribution buildpack for building applications in Java, Go, Python, Ruby, etc. The buildpacks included in 'Paketo Buildpacks' work together to create application container images that can run on any platform that supports container images (e.g., Cloud Foundry, Docker, Kubernetes, etc.).

Source: https://paketo.io/

  • I couldn't find much information on "build process" buildpacks, can you please elaborate on this?

P.s., I'm still connecting the dots with the core concepts, please see if the description is conceptually correct.


![buildpacks](/images/what.svg)

### What is a Builder?

A builder is an image that contains all the components necessary to
execute a build (for example, an ordered combination of buildpacks, a build
image and other files and configurations).

![create-builder diagram](/images/create-builder.svg)

### What is a Lifecycle?

A lifecycle is a series of steps that are used to create and manage a
buildpack. `create` is used to analyze, detect, restore, build, and export
buildpack execution. Next, `launcher` can be used to launch the application.
Finally, `rebase` can be used to push the latest changes to an existing
buildpack. All of these steps are part of a lifecycle.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Lifecycle and launcher can be used independently of each other, should we mix them both in the same initial description?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • How about the following (I guess the image may also need to be updated, please let me know the required changes):

A lifecycle is a series of steps that are used to create and manage a buildpack. The cumulative create step can be used to analyze, detect, restore, build, and export buildpack execution. All of these steps are part of a lifecycle. You can also re-enter a lifecycle using rebase to push the latest changes to an existing buildpack.

~image

launcher is an independent step that can be used to launch the application at any time.


![lifecycle](/images/lifecycle.png)

### What is a Platform

A platform typically refers to an organization or service provider (e.g.,
kpack, Tekton, Fly.io, Digital Ocean, Google Cloud, Heroku, SalesForce, etc.)
that incorporates Buildpacks within their products to make buildpack
functionality available to their end-users (typically, application
developers).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the buildpacks project we have a clear idea of what a platform is (in our platform spec). I wonder if we need to tease apart the idea of a platform and a platform oprerator in this paragraph?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Yeah, I wrestled with this during the first draft, I guess my over-simplification changed the meaning. How about the following:

What is a Platform:

A platform coordinates builds by invoking the lifecycle binary together with the buildpacks and the application source code in order to produce an executable OCI image.

Platform Operators

Platform Operators are organizations or service providers (e.g., kpack,
Tekton, Fly.io, Digital Ocean, Google Cloud, Heroku, SalesForce, etc.) that
incorporates Buildpacks within their products to make buildpack functionality
available to their end-users (typically, application developers).


A platform can be a:

- A local CLI tool
- A plugin for a continuous integration service
- A cloud application platform

## Who uses Buildpacks (Personas)

### App Developers

Regular Application developers that utilize Buildpacks in their app packaging
workflows.

### Platform Operators

Operators of platforms (Google Cloud, Salesforce, etc.) that incorporate
Buildpacks within their platforms to simplify the end-user experience.

### Buildpack Authors

Buildpacks' internal developers working on Buildpack features.
Binary file added themes/buildpacks/static/images/lifecycle.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.