# 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:

```sh
nimbus deploy
```

Check these first:

- **Your server listens on `PORT`.** See [what every app needs](apps.md#what-every-app-needs).
- **`go.mod` asks for a Go version the build supplies.** See [Go version](#go-version).
- **The module has one `main` package,** or you choose one. See [Several programs in one module](#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:

```text
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](dockerfile.md) that starts `FROM golang:<version>`. See [the deploy plan](apps.md#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:

```go
// +heroku install ./cmd/server
```

A repository with several modules is a different case; see [repositories with several apps](apps.md#repositories-with-several-apps).

## Troubleshooting

For problems that aren't specific to Go, such as an app that never answers, see [Apps troubleshooting](apps.md#troubleshooting).

### `Couldn't resolve go version`

`go.mod` asks for a newer Go than the build supplies. See [Go version](#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](#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>`.