Aspirerelease/17.0
Watch Aspire live streamsDocumentationEssayer Aspire

Get started with the Go AppHost

Ce contenu n’est pas encore disponible dans votre langue.

A Go AppHost is a Go program that defines the resources in your application and how they connect. It uses the same app model as a C# AppHost, through a Go SDK that the Aspire CLI generates from the hosting integrations you install.

  • Go 1.26 or later, with go on your PATH
  • The Aspire CLI
  • Node.js for the starter template’s React frontend
  • A container runtime if you include the optional Redis cache in the starter template. See Aspire prerequisites for the supported options.

Create a new app from the Go starter template:

Aspire CLI
aspire new aspire-go-starter -n aspire-app -o aspire-app

The template creates a Go AppHost (apphost.go), a Go API (api/), a Vite and React frontend (frontend/), and the generated SDK. The frontend waits for the API and proxies /api requests to it, and it loads /api/weatherforecast on startup. When you publish, the frontend build output is copied into the Go API container and served from ./static, so the deployed app uses one origin. Redis is optional: aspire new prompts for it interactively (default yes), and non-interactive runs omit it unless you pass --use-redis-cache true. To choose from the templates that support Go, run aspire new --language go instead.

See the aspire new command reference for all options.

The project has the following structure:

  • Répertoireaspire-app/
    • Répertoire.aspire/modules/ Generated Go SDK (do not edit)
      • aspire.go
      • base.go
      • go.mod
      • transport.go
    • Répertoire.vscode/
      • extensions.json Recommended VS Code extensions
    • Répertoireapi/ Go API that the AppHost runs
      • go.mod
      • main.go
      • telemetry.go
    • Répertoirefrontend/ Vite and React frontend
      • Répertoirepublic/
        • …
      • Répertoiresrc/
        • …
      • index.html
      • package.json
      • package-lock.json
      • vite.config.ts
      • …
    • .gitignore Keeps the generated .aspire/ directory out of source control
    • apphost.go Your AppHost entry point
    • aspire.config.json Aspire configuration
    • go.mod Go module for the AppHost

From the project directory, start the AppHost with the Aspire CLI:

Aspire CLI
aspire run

The CLI regenerates the SDK when the packages list has changed, starts the AppHost with go run ., and prints the dashboard URL. Open the dashboard to see the app Go API and frontend resources with their logs, traces, and metrics. If you included Redis, the dashboard also shows the cache resource. Open the frontend endpoint to use the React app.

The AppHost is a package main Go program. The following example shows the starter with Redis enabled. It defines a Go API, a Vite frontend that references and waits for the API, and a Redis cache:

apphost.go
package main
import (
"log"
"apphost/modules/aspire"
)
func main() {
builder, err := aspire.CreateBuilder()
if err != nil {
log.Fatal(aspire.FormatError(err))
}
// A Redis cache the API will use for read-through caching.
cache := builder.AddRedis("cache")
// Keep Go modules current and send traces, metrics, and logs to the dashboard.
api := builder.AddGoApp("app", "./api").
WithModTidy().
WithReference(cache).
WaitFor(cache).
WithHttpEndpoint(aspire.HttpEndpointEnv("PORT")).
WithHttpHealthCheck(aspire.HttpHealthCheckPath("/health")).
WithExternalHttpEndpoints().
WithOtlpExporter()
// Reference the app for Vite proxying and wait until it is healthy.
frontend := builder.AddViteApp("frontend", "./frontend").
WithReference(api).
WaitFor(api)
// Bundle the frontend into the app container for same-origin production serving.
api.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))
}
}

PublishWithContainerFiles copies the frontend build output into the Go API container at ./static when you publish. The API serves those files from the same origin as its API endpoints.

If you omit Redis, the generated AppHost has no AddRedis call, WithReference(cache), or WaitFor(cache). The frontend and publish configuration stay the same.

The program has three parts:

  1. aspire.CreateBuilder() connects to the AppHost server that the CLI starts and returns the builder.
  2. AddGoApp, AddViteApp, and the optional AddRedis add resources. Each call returns a handle, so WithReference, WaitFor, and the other configuration methods chain onto it.
  3. builder.Build() creates the application, and application.Run() blocks until the AppHost stops. Both return an error. You don’t check each resource: errors from the Add and With calls are collected and reported together when you call Build. See Go AppHost API conventions for how errors are reported and formatted.

See Deploy Go apps for publishing and deployment options.

The aspire.config.json file is the central configuration for your AppHost. This example includes the optional Redis integration:

aspire.config.json
{
"appHost": {
"path": "apphost.go",
"language": "go"
},
"packages": {
"Aspire.Hosting.Go": "17.0.0",
"Aspire.Hosting.JavaScript": "17.0.0",
"Aspire.Hosting.Redis": "17.0.0"
},
"profiles": {
"https": {
"applicationUrl": "https://localhost:17127;http://localhost:15118",
"environmentVariables": {
"ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "https://localhost:21169",
"ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:22260"
}
},
"http": {
"applicationUrl": "http://localhost:15118",
"environmentVariables": {
"ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "http://localhost:19001",
"ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "http://localhost:20115",
"ASPIRE_ALLOW_UNSECURED_TRANSPORT": "true"
}
}
}
}

If you omit Redis, the packages section contains only Aspire.Hosting.Go and Aspire.Hosting.JavaScript.

SectionDescription
appHost.pathPath to the AppHost entry point (apphost.go)
appHost.languageThe AppHost language (go)
packagesHosting integration packages and their versions. aspire add updates this section.
profilesLaunch profiles with dashboard URLs and environment variables

The .aspire/modules/ directory holds the Go SDK that the CLI generates from the packages in aspire.config.json. The CLI creates and updates it, so don’t edit these files.

FilePurpose
aspire.goTyped API for the installed integrations
base.goHandle, option, and error infrastructure
transport.goJSON-RPC transport to the AppHost server

The SDK is one Go package for all integrations. The AppHost’s go.mod file maps the apphost/modules/aspire import path to the .aspire/modules/ directory, so apphost.go imports it like any other package:

go.mod
module apphost
go 1.26
require apphost/modules/aspire v0.0.0
replace apphost/modules/aspire => ./.aspire/modules

The SDK regenerates when:

  • You run aspire add to add or update an integration
  • You run aspire run or aspire start and the package list has changed
  • You run aspire restore

The generated aspire.go includes godoc comments, so go doc and editor hover (gopls) show each API’s summary, parameters, and return value. Obsolete APIs carry a Deprecated: notice that gopls and staticcheck flag, and experimental APIs are marked with an Experimental heading.

Run aspire restore to regenerate the SDK without starting the AppHost:

Aspire CLI
aspire restore --apphost apphost.go

Restore after you clone a repository, switch branches, or edit the packages section by hand. In CI, restore before any step that compiles the AppHost, such as go build or go vet.

Use aspire add from the AppHost directory to add a hosting integration. The CLI adds the package to aspire.config.json and regenerates the Go SDK in .aspire/modules/:

Aspire CLI
aspire add postgresql

The packages section now lists the PostgreSQL integration:

aspire.config.json
{
"packages": {
"Aspire.Hosting.Go": "17.0.0",
"Aspire.Hosting.JavaScript": "17.0.0",
"Aspire.Hosting.Redis": "17.0.0",
"Aspire.Hosting.PostgreSQL": "17.0.0"
}
}

The regenerated SDK has an AddPostgres method. This AppHost adds a PostgreSQL server with one database and gives the API access to it, retaining the starter’s frontend and publish configuration. As in the previous example, omit the Redis package and cache configuration if you didn’t include Redis:

apphost.go
package main
import (
"log"
"apphost/modules/aspire"
)
func main() {
builder, err := aspire.CreateBuilder()
if err != nil {
log.Fatal(aspire.FormatError(err))
}
cache := builder.AddRedis("cache")
db := builder.AddPostgres("postgres").AddDatabase("postgresdb")
api := builder.AddGoApp("app", "./api").
WithModTidy().
WithReference(cache).
WithReference(db).
WaitFor(cache).
WaitFor(db).
WithHttpEndpoint(aspire.HttpEndpointEnv("PORT")).
WithExternalHttpEndpoints().
WithOtlpExporter()
frontend := builder.AddViteApp("frontend", "./frontend").
WithReference(api).
WaitFor(api)
api.PublishWithContainerFiles(frontend, "./static")
app, err := builder.Build()
if err != nil {
log.Fatal(aspire.FormatError(err))
}
if err := app.Run(); err != nil {
log.Fatal(aspire.FormatError(err))
}
}
  • AddPostgres adds the PostgreSQL server, and AddDatabase returns a handle for a database on that server.
  • WithReference(db) passes the connection details to the API as environment variables named after the resource, such as POSTGRESDB_URI. See Connect to PostgreSQL for a Go example that reads them.
  • WaitFor(db) starts the API after the database is ready.
  • Any error from these calls is reported when you call Build.

A Go AppHost can run resources written in other languages next to your Go apps. Add the integration for each language that you use. Python and Node.js must also be installed, because these resources run on your machine:

Aspire CLI
aspire add python
aspire add javascript

This AppHost runs a Go API and a Python recommendation service that share a Redis cache, and a Vite frontend that calls both:

apphost.go
package main
import (
"log"
"apphost/modules/aspire"
)
func main() {
builder, err := aspire.CreateBuilder()
if err != nil {
log.Fatal(aspire.FormatError(err))
}
cache := builder.AddRedis("cache")
api := builder.AddGoApp("api", "./api").
WithReference(cache).
WaitFor(cache).
WithHttpEndpoint(aspire.HttpEndpointEnv("PORT"))
recommender := builder.AddUvicornApp("recommender", "./recommender", "main:app").
WithReference(cache).
WaitFor(cache)
builder.AddViteApp("web", "./web").
WithReference(api).
WithReference(recommender).
WaitFor(api)
app, err := builder.Build()
if err != nil {
log.Fatal(aspire.FormatError(err))
}
if err := app.Run(); err != nil {
log.Fatal(aspire.FormatError(err))
}
}
  • AddUvicornApp runs a Python ASGI app. The main:app argument names the Python module and the application object in it.
  • AddViteApp runs a Vite frontend. AddUvicornApp and AddViteApp already register an http endpoint that reads its port from PORT, so only the Go API calls WithHttpEndpoint.
  • WithReference and WaitFor work the same for every resource type. The frontend receives the endpoints of the API and the recommender, and it starts after the API is ready.

See Set up JavaScript apps in the AppHost and Python integration for the options of each integration.

To debug AppHosts and their resources in Visual Studio Code, see Run, debug, and deploy.