Go

Info

This documentation is adapted for Miget purposes and is based on information from the Paketo Go Buildpack documentation.

This documentation explains how to use the Paketo buildpacks with Miget to build Go applications for several common use-cases. For more in-depth description of the buildpacks’ behavior and configuration see the Paketo Go Buildpack. For more in-depth description of the buildpack’s behavior and configuration see the Paketo Go Buildpack Reference documentation.

If your intention is to deploy an app using a Dockerfile, please refer to the Dockerfile page for guidance and best practices.

Prerequisites

The pack CLI is used throughout the examples.

Examples assume that the Paketo Base builder is the default builder:

$ pack config default-builder paketobuildpacks/builder-jammy-base

Example App

Info

A demo instance of this app is hosted at dotnet.onmiget.com.

Build

Info

The BP_KEEP_FILES variable allows to you to specity a path list of files (including file globs) that you would like to appear in the workspace of the final image. This will allow you to perserve static assests.

$ git clone git@github.com:migetapp/go-hello-world.git
$ cd go-hello-world
$ pack build --env BP_KEEP_FILES="images/*" go-hello-world

Run

$ docker run -p 5000:5000 go-hello-world

The example app should now be running on localhost:5000.

Override the Detected Go Version

The Paketo Go buildpack will attempt to automatically detect the correct version of Go to install based on the version in your app’s go.mod. It is possible to override this version by setting the BP_GO_VERSION environment variable at build time.

BP_GO_VERSION can be set to any valid semver version or version constraint (e.g. 1.14.1, 1.14.*). For the versions available in the buildpack, see the buildpack’s releases page. 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 buildpack.toml file.

With ENV variable

To configure the buildpack to use a certain version of the Go when deploying your app, set the BP_GO_VERSION environment variable at build time, or by adding it to your project.toml. See the Cloud Native Buildpacks documentation to learn more about project.toml files.

Environment Variable set under Settings -> Config Vars: BP_GO_VERSION=1.14.1

In a project.toml file

[ _ ]
schema-version = "0.2

[[ io.buildpacks.build.env ]]
  name="BP_GO_VERSION"
  value="1.14.1"

Configure the go build Command

The Paketo Go buildpack compiles Go source code with the go build command, with certain opinionated flags by default. (See reference documentation for information about the default flagset.) It is possible to override or add to these defaults by setting the BP_GO_BUILD_FLAGS and BP_GO_BUILD_LDFLAGS environment variables at build time.

Set -ldflags for go build

The Paketo Go buildpack has a dedicated environment variable for setting the value of -ldflags.

With ENV variable

When building, set BP_GO_BUILD_LDFLAGS at build time. For example, to add -ldflags="-X main.variable=some-value" to the build flagset:

Environment Variable set under Settings -> Config Vars: BP_GO_BUILD_LDFLAGS="-X main.variable=some-value"

In a project.toml file

Create a project.toml file in your app directory that sets BP_GO_BUILD_LDFLAGS at build time. For example, to add -ldflags="-X main.variable=some-value" to the build flagset, set the environment variable as follows:

[ _ ]
schema-version = "0.2"

[[ io.buildpacks.build.env ]]
  name="BP_GO_BUILD_LDFLAGS"
  value="-X main.variable=some-value"

Set Other Flags for go build

Setting BP_GO_BUILD_FLAGS will add to the Paketo Go buildpack’s default flagset. Any value that you set for a given flag will override the value set by the buildpack. See reference documentation for information about default configuration.

With ENV variable

When building, set BP_GO_BUILD_FLAGS at build time. For example, to add -buildmode=default -tags=paketo to the build flagset:

Environment Variable set under Settings -> Config Vars: BP_GO_BUILD_FLAGS="-buildmode=default -tags=paketo"

In a project.toml file

Create a project.toml file in your app directory that sets BP_GO_BUILD_FLAGS at build time. For example, to add -buildmode=default -tags=paketo to the build flagset, set the environment variable as follows:

[ _ ]
schema-version = "0.2"

[[ io.buildpacks.build.env ]]
  name="BP_GO_BUILD_FLAGS"
  value="-buildmode=default -tags=paketo"

Build Non-Default Package(s)

Build non-default second package

The Paketo Go Buildpack will compile the package in the app’s root directory by default. It is possible to build a non-default package (or packages) by setting the BP_GO_TARGETS environment variable at build time.

The following examples will build the second package in an app source directory with the structure:

app-directory
├── first
│   └── main.go
├── second
│   └── main.go
└── third
    └── main.go

With ENV variable

When building, set BP_GO_TARGETS at build time:

Environment Variable set under Settings -> Config Vars: BP_GO_TARGETS="./second"

In a project.toml file

Create a project.toml file in your app directory that sets BP_GO_TARGETS at build time.

[ _ ]
schema-version = "0.2"

[[ io.buildpacks.build.env ]]
  name="BP_GO_TARGETS"
  value="./second"

Build Multiple Packages In One App Image

The BP_GO_TARGETS environment variable can accept a colon-delimited list of target packages. Each binary will be set as a launch process of the same name in the app image. The following examples will build both the first and second packages in the same multi-package app directory as above.

With ENV variable

When building, set BP_GO_TARGETS at build time:

Environment Variable set under Settings -> Config Vars: BP_GO_TARGETS="./first:./second"

In a project.toml file

Create a project.toml file in your app directory that sets BP_GO_TARGETS at build time.

[ _ ]
schema-version = "0.2"

[[ io.buildpacks.build.env ]]
  name="BP_GO_TARGETS"
  value="./first:./second"

Import Private Go Modules

Warning

This isn't currently available at Miget. We are working on it.

Build an App that Imports Its Own Sub-Packages

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 Paketo Go Buildpack supports setting these import paths with the BP_GO_BUILD_IMPORT_PATH environment variable at build time.

The following examples will configure the buildpack to build an app whose directory structure looks like:

app-directory
├── handlers
│   └── details.go
└── main.go

and whose main.go imports:

import (
    "github.com/app-developer/app-directory/handlers"
)

With ENV variable

When building, set BP_GO_BUILD_IMPORT_PATH at build time:

Environment Variable set under Settings -> Config Vars: BP_GO_BUILD_IMPORT_PATH="github.com/app-developer/app-directory"

In a project.toml file

Create a project.toml file in your app directory that sets BP_GO_BUILD_IMPORT_PATH at build time.

[ _ ]
schema-version = "0.2"

[[ io.buildpacks.build.env ]]
  name="BP_GO_BUILD_IMPORT_PATH"
  value="github.com/app-developer/app-directory"

Prevent Source Files From Being Deleted

By default, the Paketo Go Buildpack deletes the contents of your app source directory (except for built artifacts). To preserve certain static assets that are needed in the app image, you can set the BP_KEEP_FILES environment variable at build time.

The following examples configure the buildpack to prevent the assets/ and public/ directories from being removed in the app image.

With ENV variable

When building, set BP_KEEP_FILES at build time:

Environment Variable set under Settings -> Config Vars: BP_KEEP_FILES="assets/*:public/*"

In a project.toml file

Create a project.toml file in your app directory that sets BP_KEEP_FILES at build time.

[ _ ]
schema-version = "0.2"

[[ io.buildpacks.build.env ]]
  name="BP_KEEP_FILES"
  value="assets/*:public/*"

Enable Process Reloading

Warning

This isn't currently available at Miget. We are working on it.

Override the Start Process Set by the Buildpack

Warning

This isn't currently available at Miget. We are working on it.

Enable DEBUG logging

Users of Go buildpack can access extra debug logs during the image build process by setting the BP_LOG_LEVEL environment variable to DEBUG at build time. Additional debug logs will appear in build logs if the relevant buildpacks have debug log lines.

Environment Variable set under Settings -> Config Vars: BP_LOG_LEVEL=DEBUG

Use workspace modules

Some projects depend on multi-module workspaces and use relative replace directives within the same repository. An example for this is cert-manager@v1.13.3. In such case you may want to initialize and use workspace modules prior to building.

With BP_GO_WORK_USE the Go buildpack can be configured to go work use (...) certain modules before building.

With ENV variable

When building, set BP_GO_WORK_USE at build time:

Environment Variable set under Settings -> Config Vars: BP_GO_WORK_USE=./cmd/my-module

It will run go work init before running go work use (...).