Go

A Go module deploys from its repository with no Dockerfile. Nimbus Land recognises it from go.mod, builds your program and starts it.

Quick start#

In the console, create an app from your repository with the deploy wizard. From the CLI, run this in the project directory:

nimbus deploy

Check these first:

• Your server listens on PORT. See what every app needs.
• go.mod asks for a Go version the build supplies. See Go version.
• The module has one main package, or you choose one. See Several programs in one module.

Go version#

The build picks one Go version from go.mod: a // +heroku goVersion <version> comment if present, otherwise the go directive (go 1.27.3 asks for exactly that version, go 1.27 for the newest 1.27 patch). The toolchain directive and GOTOOLCHAIN are not used.

If go.mod asks for a Go newer than the build supplies, the deploy plan says so before building:

go.mod asks for Go 1.27.4, but the build toolchain supplies Go up to 1.27.3. Set go 1.27.3 in go.mod, or add a Dockerfile that installs Go 1.27.4.

Lower the go directive, or build with a Dockerfile that starts FROM golang:<version>. See the deploy plan.

Several programs in one module#

If your module has more than one main package, none named web, and no Procfile web: line, the first deploy is blocked with This module builds more than one program. Choose the one that serves your app.

Choose the program in the deploy wizard, with program on the build API, or later on the Deployments tab. Only that program is built, and later pushes and rebuilds use it. The CLI has no flag for this: nimbus deploy prints the choices and the line to add to go.mod instead, for example:

// +heroku install ./cmd/server

A repository with several modules is a different case; see repositories with several apps.

Troubleshooting#

For problems that aren't specific to Go, such as an app that never answers, see Apps troubleshooting.

Couldn't resolve go version#

go.mod asks for a newer Go than the build supplies. See Go version.

Instances restart on a command-line tool's usage text#

The module holds several programs and the wrong one runs. Choose the right one as described under Several programs in one module, or name the server in a Procfile web: line.

Database certificate errors#

Attaching Postgres sets DATABASE_CA_CERT. Go's libpq-style drivers connect in prefer mode by default, which works as is. To verify the certificate, write DATABASE_CA_CERT to a file at start-up and use sslmode=verify-full sslrootcert=<path>.