Skip to content

Convert golang-api to a Go AppHost - #2111

Closed
David Pine (IEvangelist) wants to merge 2 commits into
mainfrom
ievangelist-go-sample-apphost
Closed

David Pine (IEvangelist) wants to merge 2 commits into
mainfrom
ievangelist-go-sample-apphost

Conversation

@IEvangelist

Copy link
Copy Markdown
Member

Important

Depends on microsoft/aspire#21183 and the Aspire 17.0 release. Ready for review, but do not merge before the 17.0.0 CLI and packages are public.

Summary

Converts samples/golang-api from a TypeScript AppHost to a Go AppHost and adds a CI job that restores, builds and vets every Go AppHost in the repository.

Closes #2110
Part of microsoft/aspire#21115

The pins stay at 17.0.0 (no prerelease or unpinned downloads), so the new go-apphosts job is expected to fail until the 17.0.0 CLI and packages are published. Re-run CI once they ship.

What changed

Sample (samples/golang-api)

  • apphost.go (new): AddDockerComposeEnvironment("env") plus AddGoApp("api", "./api") with WithModTidy(), WithHttpEndpoint (injects PORT), WithHttpHealthCheck on /health and WithExternalHttpEndpoints(). AddGoApp runs go run . locally. When publishing, it builds the API container from the checked-in api/Dockerfile (its Dockerfile generation is skipped when api/Dockerfile exists), so the image is built the same way as before.
  • go.mod (new) and aspire.config.json: appHost.path is apphost.go, language is go, and sdk.version, Aspire.Hosting.Docker and Aspire.Hosting.Go are pinned to 17.0.0. Profiles and ports are unchanged.
  • Deleted apphost.mts, package.json, package-lock.json, tsconfig.apphost.json and eslint.config.mjs. api/ is untouched.
  • README.md: describes the Go AppHost, adds a Prerequisites section (Aspire CLI 17.0+, Go 1.26+, a container runtime), shows the Go snippet with an explanation of run vs publish, and fixes the teardown step name from docker-compose-down-dc to docker-compose-down-env (step names follow the environment name; confirmed with aspire do --list-steps).

Repository

  • Root README.md: the Go API row reads "Go AppHost", and the "Aspire version" section says this sample needs the 17.0.0 CLI and SDK (the others use 13.6.0), how to install it, and which CI job uses which pin.
  • .gitattributes: *.go text eol=lf. gofmt flags CRLF files, which an autocrlf checkout on Windows would otherwise produce.
  • .github/workflows/ci.yml and build/validate-go.sh (new): a go-apphosts job. build/Build.proj only enumerates apphost.cs, *.AppHost.csproj and apphost.mts, so Go AppHosts need their own job.
    • ubuntu-24.04, 15 minute timeout, inherits the workflow-level permissions: contents: read; checkout uses persist-credentials: false.
    • actions/setup-go is pinned to a full SHA with cache: false (there is no root go.sum to key a cache on).
    • The CLI comes from a dedicated GO_APPHOST_ASPIRE_CLI_VERSION (17.0.0), so the other samples keep their own CLI pin.
    • validate-go.sh runs aspire restore --apphost ., go build -o /dev/null ./... and go vet ./... in every directory that has a tracked samples/**/apphost.go. -o /dev/null keeps go build from leaving an apphost binary in the sample directory. It fails when no Go AppHost is found, so moving or renaming the AppHost cannot turn the job into a silent pass.
    • ci-gate also needs go-apphosts.
  • No new dependencies. No sample .gitignore: the Go starter's is only .aspire/, which the root .gitignore already covers.

Validation

All checks ran in a scratch copy of samples/golang-api outside the repository, with 17.0.0-dev pins, a locally built dev Aspire CLI (17.0.0-dev, features__experimentalPolyglotGo=true), Go 1.27.0 and Docker 29.9.1. In the scratch copy apphost.go, go.mod and api/ are byte-identical to the committed files, and aspire.config.json differs only in the version pins. The released 17.0.0 CLI and packages do not exist yet, so nothing could run against the committed pins.

Command Result
aspire new aspire-go-starter --version 17.0.0-dev (scaffold comparison) apphost.go idioms, go.mod shape and aspire.config.json shape match the starter. The only difference is the starter's redundant WithOtlpExporter(), which AddGoApp already adds.
aspire restore --apphost . --non-interactive --nologo Passed. Generated .aspire/modules and resolved Aspire.Hosting.Docker and Aspire.Hosting.Go.
go build -o /dev/null ./..., go vet ./..., gofmt -l apphost.go All passed; gofmt printed nothing.
aspire run, then aspire wait api --status healthy api healthy after 9.0s.
GET /health on the api endpoint 200 {"status":"healthy"}.
aspire stop --apphost <path> --pid <pid> Exit 0, no leftover processes.
aspire publish --apphost . -o <dir> --non-interactive --nologo Exit 0, 7 of 7 steps. Wrote docker-compose.yaml and .env. api has image: "${API_IMAGE}" (no build:), PORT: "8000" and the OTEL_* variables.
docker compose config on the published output Fails with service "api" has neither an image nor a build context specified. Exit 0 once API_IMAGE=api:check is set (see Notes).
aspire do --apphost . --list-steps 26 steps, including build-api, push-api, docker-compose-up-env and docker-compose-down-env.
aspire do build-api --apphost . --non-interactive --nologo 11 of 11 steps in 15.4s. The image comes from the checked-in api/Dockerfile (User=app, HOST=0.0.0.0, Cmd ["./main"]).
docker run -d -p 127.0.0.1::8000 -e PORT=8000 <image>, then GET /health Logged Starting server on 0.0.0.0:8000; 200 {"status":"healthy"}. Container and image removed afterwards.
bash -n build/validate-go.sh (WSL Ubuntu) Exit 0. shellcheck is not installed.
build/validate-go.sh with stub aspire and go in a throwaway git repo (WSL Ubuntu) Validates only samples/**/apphost.go (ignores api/main.go and apphost.mts), prints Validated N Go AppHosts., and on failure emits ::error file=<apphost>:: and exits with the failing command's exit code without running later samples. With no apphost.go it exits 1 with ::error::No Go AppHosts found under samples/.
go build -o NUL ./... in a throwaway two-package module Exit 0 and no binary written (NUL is the Windows spelling of the null device, because /dev/null does not exist there).
PyYAML parse of ci.yml Jobs are build, go-apphosts and ci-gate; top-level permissions is contents: read; ci-gate needs build and go-apphosts; all 9 uses: references are full-SHA pinned.
git diff --check, non-ASCII scan, line-ending check Clean; 0 non-ASCII bytes; the new files are LF in the index and the working tree.
Scratch variant with ConfigureDashboard(... WithHostPort(9003)) go build, go vet and gofmt -l pass, but the AppHost panics at startup (see Notes).

Notes

  • actions/setup-go needs allow-listing. New pin: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0, the latest release (published 2026-07-16). The same SHA is pinned by microsoft/TypeScript, microsoft/sql-server-samples, microsoft/azurelinux and microsoft/onnxruntime. This repository did not use setup-go before, so an admin must add the SHA to the allowed-actions list before the job can run. actions/checkout reuses the existing pin.

  • Dashboard host port 9003 is not pinned yet (product bug). The TypeScript AppHost used configureDashboard(d => d.withHostPort({port: 9003})). The Go equivalent compiles, but the AppHost panics with a nil pointer dereference at startup, for both run and publish: the ConfigureDashboard callback receives a nil argument. The host sends the argument with the type id Aspire.Hosting/Aspire.Hosting.ApplicationModel.IResourceBuilder1[[Aspire.Hosting.Docker.DockerComposeAspireDashboardResource, ...]], but the Go SDK registers its wrapper only under Aspire.Hosting.Docker/Aspire.Hosting.Docker.DockerComposeAspireDashboardResource. wrapIfHandle (transport.go) therefore returns an unwrapped handle and callbackArg (base.go) decodes it to nil. It likely affects every Go callback whose C# parameter is Action<IResourceBuilder>, and user code cannot work around it. This PR leaves the call out, so the published dashboard port is ephemeral (ports: - "18888"). Once the product bug is fixed, replace the first line of the envdeclaration inapphost.gowith the following, which compiles and is gofmt-clean. The published port should then be"9003:18888"(expected from readingDockerComposeServiceResource.AddPorts`, not observed). Tracked in Go AppHost: callbacks that take a resource builder receive nil and panic aspire#21255.

    env := builder.AddDockerComposeEnvironment("env").
    	ConfigureDashboard(func(dashboard aspire.DockerComposeAspireDashboardResource) {
    		dashboard.WithHostPort(&aspire.WithHostPortOptions{Port: aspire.Float64Ptr(9003)})
    	})
  • WithModTidy() hides download failures. In run mode it executes go mod tidy -e. The -e flag makes tidy exit 0 even when a module cannot be downloaded; it then strips the chi require from api/go.mod and empties go.sum, leaving the tree dirty, and go run . fails with "no required module provides package". The committed api/go.mod and go.sum are complete, so nothing changes with a working network or module cache. I hit this locally when the go processes launched by the AppHost failed with x509: certificate signed by unknown authority while fetching chi from proxy.golang.org, although the same download worked from a normal shell. The cause was not identified. Pre-caching with go mod download github.com/go-chi/chi/v5@v5.2.5 avoided it.

  • Published compose output needs an image name. .env contains an empty API_IMAGE=, so docker compose config on the raw aspire publish output fails until an image is supplied. The deploy flow is expected to supply it after building and pushing the image; that path was not run (see below).

  • Not run or unverified:

    • aspire deploy, docker compose up and docker compose down end to end. Only the API image was built and run on its own.
    • The go-apphosts job on a real runner with the released CLI. The job installs no .NET SDK and relies on the SDK that ships with the ubuntu-24.04 runner image; whether the released CLI bundle works with it is unverified.
    • The dashboard UI. The locally built dev CLI could not start its dashboard executable ("The directory name is invalid", a local dev-layout problem), so aspire run was verified through aspire wait and /health only.

Replace the TypeScript AppHost with a Go AppHost that uses AddGoApp and
AddDockerComposeEnvironment. AddGoApp runs `go run .` during `aspire run`
and builds the image from the Dockerfile that is checked in next to the
API when publishing, so the API source is unchanged.

Pin the Aspire 17.0.0 SDK and packages, document the 17.0 CLI and Go 1.26
prerequisites, and correct the teardown step name to
docker-compose-down-env. Add `*.go text eol=lf` so gofmt accepts Go files
on every platform, and mark the sample as a Go AppHost in the root README.

Closes #2110
Part of microsoft/aspire#21115

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
The Aspire 13.6.0 CLI that the build job installs is too old for Go
AppHosts, and Build.proj only enumerates C# and TypeScript AppHosts, so Go
AppHosts were not covered. Add a Linux job that installs the 17.0.0 CLI
from a dedicated version variable, sets up Go with a SHA-pinned
actions/setup-go, and runs build/validate-go.sh. The script restores each
samples/**/apphost.go and runs go build and go vet on it, and fails when
no Go AppHost is found. Add the job to ci-gate.

Part of microsoft/aspire#21115

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
Copilot AI balanced review requested due to automatic review settings October 21, 2026 22:48

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Human confirmation is needed that the upstream prerequisites and public Aspire 17.0 artifacts are available, the new action is allowed, and validation passes against the committed pins.

No open issues 🎉

1 file not reviewed
  • samples/golang-api/package-lock.json: Generated file
What changed in this PR

Converts the Go API sample from a TypeScript AppHost to a native Go AppHost and adds dedicated repository CI validation for Go AppHosts.

Changes:

  • Replaces TypeScript tooling with Go orchestration while retaining local API execution and Dockerfile-based publishing.
  • Adds restore, build, and vet validation to the required CI gate.
  • Documents the sample’s separate Aspire 17.0 prerequisites and updates deployment guidance.
File Description
samples/​golang-api/​tsconfig.apphost.json Removes obsolete TypeScript compiler configuration.
samples/​golang-api/​README.md Documents Go orchestration, prerequisites, and teardown.
samples/​golang-api/​package.json Removes Node-based AppHost dependencies and scripts.
samples/​golang-api/​package-lock.json Removes the obsolete npm lockfile.
samples/​golang-api/​go.mod Defines the AppHost module and generated SDK reference.
samples/​golang-api/​eslint.config.mjs Removes obsolete TypeScript lint configuration.
samples/​golang-api/​aspire.config.json Selects Go and pins Aspire packages to 17.0.0.
samples/​golang-api/​apphost.mts Removes the previous TypeScript AppHost.
samples/​golang-api/​apphost.go Adds Go API orchestration and resource error handling.
README.md Updates the sample listing and CLI version guidance.
build/​validate-go.sh Discovers, restores, builds, and vets Go AppHosts.
.github/​workflows/​ci.yml Adds Go validation and requires it in CI Gate.
.gitattributes Enforces LF line endings for Go sources.

Review effort: Balanced

@IEvangelist

Copy link
Copy Markdown
Member Author

Closing in favor of #2173, which now includes this change (the Go AppHost conversion and the Validate Go AppHosts CI job) so it only needs one review.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Go AppHost GA] Give the Go API sample a Go AppHost

2 participants