Aspirerelease/17.0
Watch Aspire live streamsDocsTry Aspire

Deploy Go apps

Go apps are compiled, so deploying one means building a container image from the app directory. Aspire generates that image for you, so the same AddGoApp resource that you run locally is the one that you deploy to Docker Compose, Azure Container Apps, Kubernetes, and other targets.

This article is deployment-target agnostic. It explains how Go apps are containerized and how the Go starter template combines a Go API with a React frontend. For target-specific steps, see Deploy your first Aspire app, Docker Compose, and Kubernetes.

When a deployment target emits container build artifacts for a Go app, Aspire uses the app directory as the Docker build context:

  • If the app directory already contains a Dockerfile, Aspire uses it.
  • If it doesn’t, Aspire generates a multi-stage Dockerfile that builds a static Linux binary and runs it as a non-root user in a small runtime image.

For the full list of generated Dockerfile behavior, including Go version detection and private modules with WithGoPrivatewithGoPrivateWithGoPrivate, see Publish Go apps.

The Go starter template: one image for API and frontend

Section titled “The Go starter template: one image for API and frontend”

The aspire-go-starter template follows the backend serves frontend model that the JavaScript starter also uses. The Go API and the React (Vite) frontend are separate resources while you develop, but they deploy as a single container image:

  • The app resource is the Go API. It exposes /api/weatherforecast and /health.
  • The frontend resource is the React app that Vite builds.
  • PublishWithContainerFilespublishWithContainerFilesPublishWithContainerFiles copies the built frontend files into the app image at ./static.
  • The Go server serves those files from ./static at /, so the API and the user interface share one origin and one URL.
apphost.go
package main
import (
"log"
"apphost/modules/aspire"
)
func main() {
builder, err := aspire.CreateBuilder()
if err != nil {
log.Fatal(aspire.FormatError(err))
}
app := builder.AddGoApp("app", "./api").
WithModTidy().
WithHttpEndpoint(aspire.HttpEndpointEnv("PORT")).
WithHttpHealthCheck(aspire.HttpHealthCheckPath("/health")).
WithExternalHttpEndpoints().
WithOtlpExporter()
frontend := builder.AddViteApp("frontend", "./frontend", nil).
WithReference(app).
WaitFor(app)
// Bundle the frontend into the app container for same-origin production serving.
app.PublishWithContainerFiles(frontend, "./static")
application, err := builder.Build()
if err != nil {
log.Fatal(aspire.FormatError(err))
}
if err := application.Run(); err != nil {
log.Fatal(aspire.FormatError(err))
}
}

Only the app resource has an external HTTP endpoint, because it’s the only deployed container for the web surface. If you add a Redis cache, it deploys as its own resource and app receives its connection through WithReference.

During local development, the Vite dev server proxies API calls to the app resource, so you keep hot reload for the frontend. In production, the browser loads the page and calls the API from the same origin, so no CORS configuration is needed.

Add the hosting package for your target, add the environment resource to the AppHost, and run aspire deploy. The Deploy your first Aspire app tutorial walks through this for Docker Compose and Azure Container Apps with the Go starter.

To choose a different production topology, such as a reverse proxy or a separately hosted frontend, see Deploy JavaScript apps.