> ## Documentation Index
> Fetch the complete documentation index at: https://getfloo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Build a Go app on floo

> Deploy a Go web server with Postgres, sign-in, and a custom domain.

From a Go module on GitHub to a live app at `https://<app>.getfloo.app`, with managed Postgres, signed-in users, and your own domain.

New to floo? Start with the [Quickstart](https://getfloo.com/docs/introduction.md).

## What your agent controls

floo builds the `Dockerfile` in your repository. Add one that specifies the runtime for your app:

* The Go version that compiles the binary and the base image it runs on.
* System packages in the final image, such as `ffmpeg` or Chromium, each one `apk add` line.
* The build flags and the start command.
* More services from the same repository, such as a background worker or a [cron job](https://getfloo.com/docs/guides/cron-jobs.md).

Declare services, managed Postgres, sign-in, and domains in `floo.app.toml`. Store secrets outside git.

## 1. Add a Dockerfile

The module builds a single binary from the repository root. Match the `golang` image to the `go` line in `go.mod`: an older image fails with `go.mod requires go >= ...`.

```dockerfile Dockerfile theme={null}
FROM golang:1.26 AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /server .

FROM alpine:3.22
RUN apk add --no-cache ca-certificates
COPY --from=build /server /server
CMD ["/server"]
```

The final image holds the binary and CA certificates, which the TLS connection to Postgres needs. Add any system package your app runs, such as `apk add --no-cache ffmpeg`, on the same `RUN` line.

Read `PORT` and listen on all interfaces:

```go main.go theme={null}
package main

import (
	"log"
	"net/http"
	"os"
)

func main() {
	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
	}

	mux := http.NewServeMux()
	mux.HandleFunc("GET /{$}", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("ok\n"))
	})

	log.Printf("listening on :%s", port)
	log.Fatal(http.ListenAndServe(":"+port, mux))
}
```

> [!TIP]
>
> `":"+port` binds every interface. A bind to `127.0.0.1` or `localhost` makes the container unreachable and the deploy fails with `port_mismatch`.

## 2. Initialize the floo config

Install the CLI and sign in: `curl -fsSL https://getfloo.com/install.sh | bash`, then `floo auth login`. An agent can run the same journey over the HTTP API instead, starting from [getfloo.com/agents.md](https://getfloo.com/agents.md).

```bash theme={null}
floo init my-go-app
```

For a single-service Go app:

```toml floo.app.toml theme={null}
[app]
name = "my-go-app"

[services.web]
type = "web"
path = "."
port = 8080
ingress = "public"
dev_command = "go run ."
```

After adding Postgres, give the binary a `migrate` subcommand (for example with [goose](https://github.com/pressly/goose) and SQL files embedded with `embed`), then set `migrate_command = "/server migrate"` under `[services.web]`. It runs as a one-off job with the new image before traffic moves to it. A failed migration stops the deploy. Use [expand-then-contract migrations](https://getfloo.com/docs/guides/postgres.md#schema-portability-across-dev-and-prod) to keep the schema compatible with both old and new code.

## 3. Connect the repo and deploy

floo builds from your GitHub repository, not local files, so commit first. `floo deploy` pushes the commit and waits until the dev URL is live. The first time, it stops with one link if the floo GitHub App can't read the repository yet: a human opens it and installs the App on the account that owns the repository, then you run `floo deploy` again. See [Give floo access to your GitHub repository](https://getfloo.com/docs/introduction.md#2-give-floo-access-to-your-github-repository).

```bash theme={null}
git add . && git commit -m "feat: floo config + Dockerfile"
floo deploy --preflight
floo deploy
```

No GitHub repository? `floo deploy --hosted` has floo host the repository. See [Deploy without GitHub](https://getfloo.com/docs/deploy/without-github.md).

When it's done:

```bash theme={null}
floo apps show my-go-app
```

> [!TIP]
>
> **Your Go app is live** at `https://my-go-app.getfloo.app`.
>
> Every `git push origin main` ships to dev.

## 4. Add a Postgres database

```toml floo.app.toml theme={null}
[managed.default]
type = "postgres"
```

```bash theme={null}
git add floo.app.toml && git commit -m "feat: add postgres"
floo deploy --preflight
floo deploy
```

Preflight warns `MANAGED_CREDS_TO_WEB` because the web service receives the database credentials. That is expected when the web service queries the database.

`DATABASE_URL` is injected into the runtime. [pgx](https://github.com/jackc/pgx) reads it as is, TLS settings included:

```bash theme={null}
go get github.com/jackc/pgx/v5
```

```go main.go theme={null}
import (
	"context"
	"fmt"
	"log"
	"net/http"
	"os"
	"time"

	"github.com/jackc/pgx/v5/pgxpool"
)

func main() {
	pool, err := pgxpool.New(context.Background(), os.Getenv("DATABASE_URL"))
	if err != nil {
		log.Fatal(err)
	}
	defer pool.Close()

	mux := http.NewServeMux()
	mux.HandleFunc("GET /{$}", func(w http.ResponseWriter, r *http.Request) {
		var now time.Time
		if err := pool.QueryRow(r.Context(), "select now()").Scan(&now); err != nil {
			http.Error(w, err.Error(), http.StatusInternalServerError)
			return
		}
		fmt.Fprintf(w, "db time: %s\n", now.Format(time.RFC3339))
	})
	// ... read PORT and ListenAndServe as above
}
```

`pgxpool.New` connects on first use, so the server starts and answers while Postgres wakes. Dev and prod each get a separate Postgres database and credentials, with no shared state.

## 5. Add per-user auth

Set `access_mode = "accounts"` and floo handles sign-in:

```toml floo.app.toml theme={null}
[app]
name = "my-go-app"
access_mode = "accounts"
```

From the next deploy onward, floo's gateway:

* Redirects unauthenticated requests to a hosted login page.
* Validates the session cookie on every request.
* Injects identity headers into every request that reaches your Go server.

Handlers read the headers, with no auth code, callback handlers, or session storage. Add `encoding/json` to the imports:

```go theme={null}
type User struct {
	Email string `json:"email"`
	ID    string `json:"id"`
	Name  string `json:"name"`
}

func requireUser(next func(http.ResponseWriter, *http.Request, User)) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		u := User{
			Email: r.Header.Get("X-Floo-User-Email"),
			ID:    r.Header.Get("X-Floo-User-Id"),
			Name:  r.Header.Get("X-Floo-User-Name"),
		}
		if u.Email == "" || u.ID == "" {
			http.Error(w, "unauthorized", http.StatusUnauthorized)
			return
		}
		next(w, r, u)
	}
}

mux.HandleFunc("GET /me", requireUser(func(w http.ResponseWriter, r *http.Request, u User) {
	w.Header().Set("Content-Type", "application/json")
	json.NewEncoder(w).Encode(u)
}))
```

Locally, run `floo dev --fixture-user` (see [section 7](#7-local-development-with-dev-credentials)) or send the headers yourself with `curl -H 'X-Floo-User-Email: you@example.com' ...`. Access modes and identity headers in full: [App sign-in](https://getfloo.com/docs/guides/app-auth.md).

## 6. Add a custom domain

Declare the domain in `floo.app.toml`:

```toml theme={null}
[domains."app.example.com"]
service = "web"
```

Commit and push, wait for that commit's dev deploy to go live, then release it
to prod and read the DNS records:

Replace `owner/repo` with your GitHub repository. For a floo-hosted project, see [Environments](https://getfloo.com/docs/guides/environments.md#the-flow).

```bash theme={null}
gh release create v1 --repo owner/repo
```

Wait for the prod deploy to finish, then read the DNS records:

```bash theme={null}
floo domains show app.example.com --app my-go-app
```

Publish the traffic and certificate CNAME records that `show` prints, then watch
activation:

```bash theme={null}
floo domains watch app.example.com --app my-go-app
```

`net/http` serves every host by default. If you build absolute URLs, read the host from `X-Forwarded-Host`. DNS setup and troubleshooting: [Custom domains](https://getfloo.com/docs/guides/custom-domains.md).

## 7. Local development with dev credentials

```bash theme={null}
floo dev --app my-go-app
```

Runs `dev_command` locally with `DATABASE_URL` and readable env vars from the app's dev environment: a real connection to your dev Postgres, with no credentials in your shell history. Write-only secrets are withheld; supply separate local values when needed. Prod credentials never reach a local session.

The database exists after the first deploy that declares `[managed.default]`. Before that deploy, `floo dev` starts without `DATABASE_URL`.

To test signed-in flows, add `--fixture-user`:

```bash theme={null}
floo dev --app my-go-app --fixture-user you@example.com
```

`floo dev` then puts a proxy in front of each accounts-mode service that injects the same `X-Floo-User-*` headers floo's gateway adds in production. The output table shows the raw service URL and the auth-proxied URL; use the auth-proxied one for any path that reads identity headers.

## Common gotchas

* **`/healthz` is reserved.** floo's edge intercepts that exact path. Use `/health` or `/livez`.
* **Listen on `":"+port`.** floo cannot reach `127.0.0.1`.
* **`CGO_ENABLED=0` for a static binary.** A cgo build links against the build image's glibc and fails to start on Alpine. If you need cgo, run the final stage on `debian:bookworm-slim` instead.
* **CA certificates in the final image.** Without them, TLS to Postgres and outbound HTTPS calls fail with `x509: certificate signed by unknown authority`.
* **`X-Forwarded-Proto`.** floo's edge terminates TLS and forwards `X-Forwarded-Proto: https`. `r.TLS` is always `nil` inside the container.

## Next steps

> [card] [App sign-in](https://getfloo.com/docs/guides/app-auth.md)
>
> Identity headers, access policies, and access modes in detail.

> [card] [Cron jobs](https://getfloo.com/docs/guides/cron-jobs.md)
>
> Run a subcommand of the same binary on a schedule.

> [card] [Dockerfiles](https://getfloo.com/docs/guides/dockerfiles.md)
>
> Layer order for fast pushes and recommended multi-stage builds.

> [card] [Production environments](https://getfloo.com/docs/guides/environments.md)
>
> Dev vs prod, promotion, env overrides.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.