# Deploy a Go app

Deploy a Go web server on Hangar from its repository, built as a static binary with no Dockerfile, with PostgreSQL and HTTPS on your domain.

A Go server deploys on Hangar straight from its repository. The automatic builder compiles it into a small static binary and runs it as a long-lived process, so goroutines, WebSockets and in-memory caches work as they do on your machine.

## Before you start

- A Go module in a Git repository, with `go.mod` at the root.
- A [Hangar account](https://tryhangar.io/register).

## 1. Listen on the right address

Read the port from `PORT` and listen on all interfaces. A Go address such as `:8080` already means every interface:

```go
port := os.Getenv("PORT")
if port == "" {
	port = "8080"
}
log.Fatal(http.ListenAndServe(":"+port, mux))
```

> [!WARNING]
> Do not listen on `127.0.0.1:8080`: the proxy in front of your service could not reach it.

## 2. Create the service

Create a project, add a service and pick your repository and branch. Choose the region closest to your users and leave the builder on **Automatic**. It detects `go.mod`, uses the Go version declared there, downloads the modules and builds the binary.

If the repository has several programs, the builder takes the root package when it has Go files, otherwise the first directory under `cmd/`. To pick another one, set this variable in the **Variables** tab:

```env
RAILPACK_GO_BIN=cmd/api
```

## 3. Set the variables

Hangar sets `PORT` to the domain's container port, so the code above listens on `8080` once you add the domain below. Set your own configuration in the **Variables** tab.

## 4. Deploy and add a domain

Deploy the service. In **Settings → Networking**, add a domain with container port `8080` and HTTPS on.

## Adding PostgreSQL

Add a **PostgreSQL** service in the same project and region, copy its **internal connection URL** and set it on the app:

```env
DATABASE_URL=<the internal connection URL>
```

With [pgx](https://github.com/jackc/pgx):

```go
pool, err := pgxpool.New(ctx, os.Getenv("DATABASE_URL"))
```

Run migrations, with a tool such as goose or golang-migrate, from your program at startup or as the service's [pre-deploy command](https://tryhangar.io/docs/builds#pre-deploy-command).

## Shut down cleanly

On every deploy the old container receives `SIGTERM` before it stops. Catch it and let requests in flight finish:

```go
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
go srv.ListenAndServe()
<-ctx.Done()
srv.Shutdown(context.Background())
```

## Troubleshooting

- **502 on the domain**: the server listens on `127.0.0.1`, or on a port other than the domain's container port.
- **The wrong program starts**: set `RAILPACK_GO_BIN` to the package you want.
- **`cgo` or C library errors**: set `CGO_ENABLED=1`, or build with a [Dockerfile](https://tryhangar.io/guides/deploy-dockerfile).

## Frequently asked questions

### Do I need a Dockerfile to deploy Go on Hangar?

No. The automatic builder detects go.mod, compiles your app into a static binary with the Go version from go.mod and runs it. A Dockerfile is only needed for unusual builds.

### How does Hangar pick the package to build in a repository with several commands?

It builds the root package if it has Go files, otherwise the first directory under cmd/. To choose another one, set the RAILPACK_GO_BIN variable to its path, for example cmd/api.

### Does cgo work?

Builds use CGO_ENABLED=0 by default, which gives a static binary. Set the CGO_ENABLED=1 variable if your app needs cgo, for example for SQLite through mattn/go-sqlite3.
