The Go Paketo Buildpack supports several popular configurations for Go apps.
To build a sample app locally with this buildpack using the
pack CLI, run
git clone https://github.com/paketo-buildpacks/samples cd samples/go/mod pack build my-app --buildpack gcr.io/paketo-buildpacks/go \ --builder paketobuildpacks/builder:baseCopied!
See samples for how to run the app.
NOTE: Though the example above uses the Paketo Base builder, this buildpack is also compatible with the Paketo Full builder and Paketo Tiny builder.
The Go Paketo Buildpack supports several versions of Go. For more details on the specific versions supported in a given buildpack version, see the release notes.
The Go CNB (Cloud Native Buildpack) allows you to specify a version of Go to use during deployment. This
version can be specified via
go.mod. When specifying a version of Go,
you must choose a version that is available within the buildpack. The supported
versions can be found
The buildpack prioritizes the versions specified in
each possible configuration location with the following precedence, from
highest to lowest:
Specifying a version of Go is not required. In the case that is not specified,
the buildpack will provide the default version, which can be seen in the
To configure the buildpack to use Go v1.14.6 when deploying your app, include
the values below in your
--- go: version: 1.14.6Copied!
go build command supports a number of flags that allow users to override
defaults for more control over build configurations. By default, the buildpack
sets the following build flags:
-mod=vendor(if there is a go.mod file in the app source code)
To set custom values for your build flags or override the defaults, assign a
list of flags to the
BP_GO_BUILD_FLAGS environment variable as shown below:
BP_GO_BUILD_FLAGS=-buildmode=some-build-mode -tags=paketo,production -ldflags="-X main.variable=some-value" -raceCopied!
Specifying the Go Build flags through buildpack.yml configuration will be deprecated in Go Build Buildpack v1.0.0. To migrate from using buildpack.yml please set the $BP_GO_BUILD_FLAGS environment variable.
The Go CNB allows users to specify multiple targets for
go build. This will
result in multiples binaries being built.Targets must be a list of paths
relative to the root directory of the source code.
To set custom targets for your build assign a list of targets to the
$BP_GO_TARGETS environment variable as shown below:
Specifying the Go Build targets through buildpack.yml configuration will be deprecated in Go Build Buildpack v1.0.0. To migrate from using buildpack.yml please set the $BP_GO_TARGETS environment variable.
If you are building a $GOPATH application that imports its own sub-packages,
you will need to specify the import paths for those sub-packages. The Go CNB
supports setting these import paths via the
Specifying the Go Build import path through buildpack.yml configuration will be deprecated in Go Build Buildpack v1.0.0. To migrate from using buildpack.yml please set the $BP_GO_BUILD_IMPORT_PATH environment variable.
The Go CNB by defaults deletes the contents of your app root once it has
compiled your app in an effort to optimize the size the final image. However
sometimes there are static assets that you would like to appear in the final
image. To have these files or directories persist set the
environment variable, which can be passed to
With the Go CNB, there are three options for package management depending on your application:
Support for each of these package managers is mutually-exclusive. You can find specific information for each option below.
Many Go apps require third-party libraries to perform common tasks and
behaviors. Go modules are a built-in option for managing these third-party
dependencies that the Go CNB fully supports. Including a
go.mod file in your
app source code instructs the buildpack to vendor your dependencies using Go
modules. During the build phase, the
buildpack checks to see
if the application requires any external modules and if it does, runs the
go mod vendor command for your app. The resulting
vendor directory will exist
in the app’s root directory and will contain all the packages needed to build
your Go app.
Dep is an alternative option to Go Modules for package management in Go apps.
Gopkg.toml file (more information about this
here) in your app source
code instructs the buildpack to download the
dep package, and then vendor
your dependencies using it. There may be an optional
Gopkg.lock file that
outlines specific versions of the dependencies to be packaged. During its build
buildpack runs the
dep ensure command for your app. The resulting
vendor directory will exist in
the app’s root directory and will contain all the packages needed to build your
The Go CNB also supports both self-vendored apps and simpler apps that do not
require third-party packages. In this case there is no vendoring step, and the
go build command is run on the app source code as it is provided.
The Go CNB sets a few environment variables during the
phases of the app lifecycle. The sections below describe each environment
variable and its impact on your app.
GOPATH environment variable tells Go where to look for artifacts such as
source code and binaries. The Go CNB takes care of setting the
you, depending on your app and which package management option your app uses.
When using Go modules, the Go CNB sets the
GOPATH to a cached module layer in
the image so that between builds of the app, the dependencies don’t have to be
redownloaded. Essentially, the
GOPATH is being used to tell the
go mod vendor command where to look for dependencies. It’s worth noting that in this
GOPATH isn’t persisted beyond vendoring the dependencies and gets
overwritten by a subsequent buildpack.
When using the Dep tool, the Go CNB sets the
GOPATH to a temporary directory.
The app source code gets copied into the
GOPATH location so that the
dep ensure command knows where to look for the source code, as well as where to
vendor directory. The
vendor directory that is created is then
copied to the original source code directory. The
GOPATH in this case is used
dep ensure, but does not persist beyond that step.
go-build buildpack participates in the Go CNB in every case, regardless
of which package management option is used. The
GOPATH is set to a temporary
directory which includes the app source code and local sub-packages. The
GOPATH is utilized in running
go build to compile your app.
GOCACHE variable specifies where build outputs are stored for reuse in
subsequent builds. It gets set to a cached layer in the image by the
go-build buildpack, so that it is persisted between builds.
DEPCACHEDIR specifies where upstream dependency source code is stored for use
by the Dep tool. The
dep-ensure buildpack sets this variable to the path of a
cache layer in the app image.
Last modified: January 12, 2021