search

heroku / heroku-buildpack-go

Heroku's classic buildpack for Go applications.
https://devcenter.heroku.com/categories/go-support
MIT License
794 stars 513 forks source link
buildpack go golang heroku heroku-languages

readme

Heroku Buildpack for Go

CI

Heroku Buildpack for Go

This is the official Heroku buildpack for Go.

Getting Started

Follow the guide at https://devcenter.heroku.com/articles/getting-started-with-go

There's also a hello world sample app at https://github.com/heroku/go-getting-started

Example

$ ls -A1
.git
vendor
Procfile
web.go

$ heroku create
Creating polar-waters-4785...
...

$ git push heroku main
...
-----> Go app detected
-----> Installing go1.11... done
-----> Running: go install -tags heroku .
-----> Discovering process types
       Procfile declares types -> web

-----> Compressing... done, 1.6MB
-----> Launching... done, v4
       https://polar-waters-4785.herokuapp.com/ deployed to Heroku

This buildpack will detect your repository as Go if you are using either:

This buildpack adds a heroku build constraint, to enable heroku-specific code. See the App Engine build constraints article for more info.

Go Module Specifics

When using go modules, this buildpack will search the code base for main packages, ignoring any in vendor/, and will automatically compile those packages. If this isn't what you want you can specify specific package spec(s) via the go.mod file's // +heroku install directive (see below).

The go.mod file allows for arbitrary comments. This buildpack utilizes build constraint style comments to track Heroku build specific configuration which is encoded in the following way:

If a top level vendor directory exists and the go.sum file has a size greater than zero, go install is invoked with -mod=vendor, causing the build to skip downloading and checking of dependencies. This results in only the dependencies from the top level vendor directory being used.

Pre/Post Compile Hooks

If the file bin/go-pre-compile or bin/go-post-compile exists and is executable then it will be executed either before compilation (go-pre-compile) of the repo, or after compilation (go-post-compile).

These hooks can be used to install additional tools, such as github.com/golang-migrate/migrate:

#!/bin/bash
set -e

go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@v4.15.1

Because the buildpack installs compiled executables to bin, the go-post-compile hook can be written in go if it's installed by the specified <packagespec> (see above).

Example:

$ cat go.mod
// +heroku install ./cmd/...
$ ls -F cmd
client/ go-post-compile/ server/

dep specifics

The Gopkg.toml file allows for arbitrary, tool specific fields. This buildpack utilizes this feature to track build specific configuration which are encoded in the following way:

[metadata.heroku]
  root-package = "github.com/heroku/fixture"
  go-version = "go1.8.3"
  install = [ "./cmd/...", "./foo" ]
  ensure = "false"
  additional-tools = ["github.com/golang-migrate/migrate"]
...

govendor specifics

The vendor.json spec that govendor follows for its metadata file allows for arbitrary, tool specific fields. This buildpack uses this feature to track build specific bits. These bits are encoded in the following top level json keys:

Example with everything, for a project using go1.9, located at $GOPATH/src/github.com/heroku/go-getting-started and requiring a single package spec of ./... to install.

{
    ...
    "rootPath": "github.com/heroku/go-getting-started",
    "heroku": {
        "install" : [ "./..." ],
        "goVersion": "go1.9"
         },
    ...
}

A tool like jq or a text editor can be used to inject these variables into vendor/vendor.json.

glide specifics

The glide.yaml and glide.lock files do not allow for arbitrary metadata, so the buildpack relies solely on the glide command and environment variables to control the build process.

The base package name is determined by running glide name.

The Go version used to compile code defaults to the buildpack's DefaultVersion. This can be overridden by the $GOVERSION environment variable. Setting $GOVERSION to a major version will result in the buildpack using the latest released minor version in that series. Setting $GOVERSION to a specific minor Go version will pin Go to that version. Since Go doesn't release .0 versions, specifying a .0 version will pin your code to the initial release of the given major version (ex go1.10.0 == go1.10 w/o auto updating to go1.10.1 when it becomes available).

Examples:

heroku config:set GOVERSION=go1.9   # Will use go1.9.X, Where X is that latest minor release in the 1.9 series
heroku config:set GOVERSION=go1.7.5 # Pins to go1.7.5

glide install will be run to ensure that all dependencies are properly installed. If you need the buildpack to skip the glide install you can set $GLIDE_SKIP_INSTALL to true. Example:

heroku config:set GLIDE_SKIP_INSTALL=true
git push heroku main

Installation defaults to .. This can be overridden by setting the $GO_INSTALL_PACKAGE_SPEC environment variable to the package spec you want the go tool chain to install. Example:

heroku config:set GO_INSTALL_PACKAGE_SPEC=./...
git push heroku main

Usage with other vendoring systems

If your vendor system of choice is not listed here or your project only uses packages in the standard library, create vendor/vendor.json with the following contents, adjusted as needed for your project's root path.

{
    "comment": "For other heroku options see: https://devcenter.heroku.com/articles/go-support",
    "rootPath": "github.com/yourOrg/yourRepo",
    "heroku": {
        "sync": false
    }
}

Default Procfile

If there is no Procfile in the base directory of the code being built and the buildpack can figure out the name of the base package (also known as the module), then a default Procfile is created that includes a web process type that runs the resulting executable from compiling the base package.

For example, if the package name was github.com/heroku/example, this buildpack would create a Procfile that looks like this:

$ cat Procfile
web: example

This is useful when the base package is also the only main package to build.

If you have adopted the cmd/<executable name> structure this won't work and you will need to create a Procfile.

Note: This buildpack should be able to figure out the name of the base package in all cases, except when gb is being used.

Private Git Repos

The buildpack installs a custom git credential handler. Any tool that shells out to git (most do) should be able to transparently use this feature. Note: It has only been tested with Github repos over https using personal access tokens.

The custom git credential handler searches the application's config vars for vars that follow the following pattern: GO_GIT_CRED__<PROTOCOL>__<HOSTNAME>. Any periods (.) in the HOSTNAME must be replaces with double underscores (__).

The value of a matching var will be used as the username. If the value contains a ":", the value will be split on the ":" and the left side will be used as the username and the right side used as the password. When no password is present, x-oauth-basic is used.

The following example will cause git to use the FakePersonalAccessTokenHere as the username when authenticating to github.com via https:

heroku config:set GO_GIT_CRED__HTTPS__GITHUB__COM=FakePersonalAccessTokenHere

Hacking on this Buildpack

To change this buildpack, fork it on GitHub & push changes to your fork. Ensure that tests have been added to test/run.sh and any corresponding fixtures to test/fixtures/<fixture name>.

Tests

Make, jq & docker are required to run tests.

make test

Run a specific test in test/run.sh:

make BASH_COMMAND='test/run.sh -- testGBVendor' test

Compiling a fixture locally

Make & docker are required to compile a fixture.

make FIXTURE=<fixture name> compile

You will then be dropped into a bash prompt in the container that the fixture was compiled in.

Using with cgo

The buildpack supports building with C dependencies via cgo. You can set config vars to specify CGO flags to specify paths for vendored dependencies. The literal text of ${build_dir} will be replaced with the directory the build is happening in. For example, if you added C headers to an includes/ directory, add the following config to your app: heroku config:set CGO_CFLAGS='-I${ build_dir}/includes'. Note the usage of '' to ensure they are not converted to local environment variables.

Using a development version of Go

The buildpack can install and use any specific commit of the Go compiler when the specified go version is devel-<short sha>. The version can be set either via the appropriate vendoring tools config file or via the $GOVERSION environment variable. The specific sha is downloaded from Github w/o git history. Builds may fail if GitHub is down, but the compiled go version is cached.

When this is used the buildpack also downloads and installs the buildpack's current default Go version for use in bootstrapping the compiler.

Build tests are NOT RUN. Go compilation failures will fail a build.

No official support is provided for unreleased versions of Go.

Passing a symbol (and optional string) to the linker

This buildpack supports the go linker's ability (-X symbol value) to set the value of a string at link time. This can be done by setting GO_LINKER_SYMBOL and GO_LINKER_VALUE in the application's config before pushing code. If GO_LINKER_SYMBOL is set, but GO_LINKER_VALUE isn't set then GO_LINKER_VALUE defaults to $SOURCE_VERSION.

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

Testpack

This buildpack supports the testpack API used by Heroku CI.

Golanglint-ci

If the source code contains a golanglint-ci configuration file in the root of the source code (one of /.golangci.yml, /.golangci.toml, or /.golangci.json) then golanci-lint is run at the start of the test phase.

Use one of those configuration files to configure the golanglint-ci run.