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
GOPACKAGENAMEenvironment variable specified and has any files ending with.go. - Your app has a
glide.ymlfile and is using glide, starting in buildpack version 1.7.9. - Your app has a
Gopkg.tomlfile 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.
