Go buildpack

Page last updated:

Supported versions

You can find supported Go versions in the Cloud Foundry release notes.

Push an app

The Go buildpack is automatically detected in the following circumstances:

  • Your app has been packaged with godep using godep save.
  • Your app has a vendor/ directory and has any files ending with .go.
  • Your app has a GOPACKAGENAME environment variable specified and has any files ending with .go.
  • Your app has a glide.yml file and is using glide, starting in buildpack version 1.7.9.
  • Your app has a Gopkg.toml file and is using dep, starting in buildpack version 1.8.9.

If your Cloud Foundry deployment does not have the Go Buildpack installed, or the installed version is out of date, you can use the latest version with the command:

$ cf push my_app -b https://github.com/cloudfoundry/go-buildpack.git

When you specify versions, specify only majoror minor versions, such as Go 1.6, rather than Go 1.6.0. This ensures you receive the most recent patches.

Start command

When pushing Go apps, you can specify a start command for the app. You can place the start command in the Procfile file in root directory of your app. For example, if the binary generated by your Go project is my-go-server, your Procfile could contain the following:

web: my-go-server

For more information about Procfiles, see the Configuring a Production Server topic.

You can also specify the start command for your app in the manifest.yml file in the root directory. For example, your manifest.yml could contain the following:

---
applications:
  - name: my-app-name
    command: my-go-server

If you do not specify a start command in a Procfile, in the manifest, or with the -c flag for cf push, the generated binary is used as the start command. Example: my-go-server

Push an app with Go modules

As of Go 1.11 you can use the go mod vendoring tool that comes with Go. If you are using go mod to package your dependencies, make sure that you have created a valid go.mod file in the root directory of your app by running go mod init.

Go sample app

An example go.mod file:

module go-online

require (
    github.com/BurntSushi/toml v0.3.1
    github.com/satori/go.uuid v1.2.0
)

When your main package is not in the project root

A common project pattern is to place main packages in a subdirectory called cmd like in the example below:

$ tree app-package-name
app-package-name
├── cmd
│   ├── cli
│   │   └── main.go
│   └── server
│       └── main.go
├── go.mod
├── go.sum
├── shared.go
├── shared_test.go
└── manifest.yml

When you configure your project like this, set the environment variable GO_INSTALL_PACKAGE_SPEC to $MODULE_NAME/$MAIN_PACKAGE_PATH.

If the module name for the above app-package-name app is example.com/user/app-package-name, the value of GO_INSTALL_PACKAGE_SPEC must be example.com/user/app-package-name/cmd/server.

If you want to put this in your manifest.yml, see the following example:

---
applications:
- name: app-package-name
  env:
    GO_INSTALL_PACKAGE_SPEC: example.com/user/app-package-name/cmd/server

Push an app with godep

If you are using godep to package your dependencies, make sure that you have created a valid Godeps/Godeps.json file in the root directory of your app by running godep save.

When using godep, you can fix your Go version in GoVersion key of the Godeps/Godeps.json file.

Go sample app

An example Godeps/Godeps.json:

{
    "ImportPath": "go_app",
    "GoVersion": "go1.6",
    "Deps": []
}

Push an app with Glide

If you use glide to specify or package your dependencies, make sure that you have created a valid glide.yml file in the root directory of your app by running glide init.

To vendor your dependencies before pushing, run glide install. This generates a vendor directory and a glide.lock file specifying the latest compatible versions of your dependencies. You must have a glide.lock file when pushing a vendored app. You do not need a glide.lock file when deploying a non-vendored app.

Glide

An example glide.yml file:

package: go_app_with_glide
import:
- package: github.com/ZiCog/shiny-thing
  subpackages:
  - foo

You can specify Go version in the manifest.yml file:

---
applications:
  - name: my-app-name
    env:
      GOVERSION: go1.8

Push an app with dep

If you use dep to specify or package your dependencies, make sure that you have created a valid Gopkg.toml file in the root directory of your app by running dep init.

To vendor your dependencies before pushing, run dep ensure. This generates a vendor directory and a Gopkg.lock file specifying the latest compatible versions of your dependencies. You must have a Gopkg.lock file when pushing a vendored app. You do not need a Gopkg.lock file when deploying a non-vendored app.

dep

An example Gopkg.toml file:

[[constraint]]
  branch = "main"
  name = "github.com/ZiCog/shiny-thing"

You can specify Go version in the manifest.yml file:

---
applications:
  - name: my-app-name
    env:
      GOVERSION: go1.8

Push an app without a vendoring tool

You can use Go without a vendoring tool by packaging all local dependencies in the vendor/ directory, and by specifying the app package name in the GOPACKAGENAME environment variable.

An example manifest.yml:

---
applications:
  - name: my-app-name
    command: go-online
    env:
      GOPACKAGENAME: example.com/user/app-package-name

Pass a symbol and string to the Go Linker

The Go buildpack supports the Go linker’s ability, -X symbol value, to set the value of a string at link time. Set the GO_LINKER_SYMBOL and GO_LINKER_VALUE in the application’s configuration before pushing code.

This can be used to embed the commit SHA or other build-specific data directly into the compiled executable.

For a sample Go app, see the go-buildpack repository on GitHub.

C dependencies

The Go buildpack supports building with C dependencies using cgo. You can set config vars to specify cgo flags to, for example, specify paths for vendored dependencies. As an example, to build gopgsqldriver, add the config var CGO_CFLAGS with the value -I/app/code/vendor/include/postgresql and include the relevant Postgres header files in vendor/include/postgresql/ in your app.

Proxy support

If you need to use a proxy to download dependencies during staging, you can set the http_proxy and/or https_proxy environment variables. For more information, see Using a Proxy.

BOSH configured custom trusted certificate support

Go uses certificates stored in /etc/ssl/certs. Your platform operator can configure the platform to add the custom certificates into the application container.

Help and support

Join the #buildpacks channel in our Slack community if you need any further assistance.

For more information about using and extending the Go buildpack in Cloud Foundry, see the go-buildpack GitHub repository.

You can find current information about this buildpack on the Go buildpack release page in GitHub.

View the source for this page in GitHub