Developer experience: add an Aspire AppHost for local orchestration and observability #565

Problem

The normal local-development path is split across several commands and configuration surfaces:

1. start PostgreSQL and optionally Redis with deploy/docker-compose.dev.yml;
2. launch Cluckwork.Api with the correct Development environment, user-secrets, and fixed port;
3. launch the React/Vite SPA separately;
4. configure an OTLP receiver separately to inspect the telemetry the API already emits.

This works, but it leaves resource startup, dependency readiness, dynamic endpoints, health, logs, traces, and metrics spread across Compose, VS Code, Vite, and operator knowledge.

Proposal

Add a project-based Aspire AppHost as a local-development entry point. Aspire 13.5 uses the .NET 10 SDK already targeted by Cluckwork and can model the existing .NET API, React/Vite SPA, PostgreSQL, and Redis without changing the domain/application architecture.

The AppHost should:

• model the current PostgreSQL 18.4 database and Redis 7.4 shared-state backend as local container resources;
• preserve the repository's exact digest-pinned container images rather than accepting floating Aspire defaults;
• launch Cluckwork.Api explicitly in Development and continue loading its existing user-secrets;
• supply the PostgreSQL resource as ConnectionStrings:Default;
• map the Redis resource connection string to SharedState:Redis:ConnectionString;
• launch web/ through Aspire's Vite integration and set VITE_API_TARGET from the API's dynamically allocated endpoint;
• express readiness ordering: database and Redis before API, API before Vite;
• use the existing /health/live and /health/ready contracts in the Aspire resource model;
• feed the API's existing OpenTelemetry traces and metrics into the Aspire dashboard;
• show each resource's status and console logs in the dashboard.

A representative resource graph is:

PostgreSQL ─┐
Redis ──────┼──> Cluckwork.Api ───> React/Vite
            └──> Aspire dashboard: resources, logs, traces, metrics, health

Telemetry integration

Do not add the stock Aspire ServiceDefaults implementation unchanged. Cluckwork already has stronger, application-specific behavior in AddCluckworkTelemetry and its health pipeline:

• sensitive-data redaction before sinks;
• fail-closed endpoint/protocol validation;
• special degradation behavior for one-shot commands such as migrate and recover-admin;
• an always-on server sampler and Cluckwork-specific instrumentation/filtering;
• /health/live and /health/ready, rather than the template /alive and /health contract.

Instead, make the existing telemetry registration honor Aspire's standard OTEL_EXPORTER_OTLP_* environment variables when the corresponding Otlp:* setting is absent. Explicit Otlp:* configuration remains authoritative, and all current production validation, redaction, and one-shot behavior remains intact. Cover precedence, malformed configuration, and one-shot behavior with tests.

Acceptance criteria

• A project-based Cluckwork.AppHost is part of Cluckwork.sln and uses a pinned stable Aspire release compatible with .NET 10.
• aspire run from the repository starts PostgreSQL, Redis, the API, the Vite SPA, and the secured local Aspire dashboard with no separately entered connection strings or fixed API port.
• PostgreSQL and Redis use the same versions and immutable image digests as the existing dev/reference/test stacks; their pins cannot silently drift apart.
• PostgreSQL data persists across ordinary AppHost restarts, with PostgreSQL 18's data-directory semantics handled correctly.
• The API starts in Development, loads user-secrets, migrates the fresh local database using the existing Development behavior, and becomes healthy at /health/ready.
• The SPA's same-origin /api calls reach the Aspire-started API through its existing Vite proxy and a dynamically supplied VITE_API_TARGET.
• Redis is wired to SharedState:Redis:ConnectionString, so local Aspire runs exercise the real shared-state path rather than the in-process fallback.
• Dashboard resource status and console logs work, and API traces and metrics arrive through OTLP after exercising at least one API request and one EF query.
• Existing telemetry redaction, production TLS checks, sampling/filtering, and one-shot process-role behavior remain unchanged and covered by tests.
• Existing /health/live and /health/ready behavior remains unchanged; no duplicate template health endpoints or instrumentation are introduced.
• No credentials, JWT keys, connection strings, or generated Aspire parameter values are committed.
• NuGet lock files are regenerated and committed; locked restore remains green.
• CONTRIBUTING.md and the relevant development documentation describe aspire run, prerequisites, dashboard access, reset/persistence behavior, and the existing dependency-only Compose fallback.
• Verification includes dotnet build Cluckwork.sln, dotnet test Cluckwork.sln, frontend typecheck/tests, and a documented runtime smoke test through the Aspire-started SPA.

Out of scope

• Replacing the production Dockerfile or deploy/docker-compose.yml.
• Using the AppHost as the production runtime.
• Adopting aspire publish/aspire deploy or changing the digest-based release and attestation pipeline.
• Replacing the separate production migrate job or changing the serving process's no-DDL contract.
• Replacing the simulation harness or the existing Testcontainers integration-test infrastructure.
• Changing the DDD layers, endpoint contracts, persistence model, or SPA product behavior.
• Adding pgAdmin/Redis Insight in the initial slice; those can be evaluated separately after the minimal resource graph is stable.

Rollout

Keep deploy/docker-compose.dev.yml as the documented dependency-only fallback during the first slice. Aspire becomes the preferred full-stack local entry point only after the runtime smoke test demonstrates parity. Production and simulation paths remain authoritative for their current purposes.

References

• Add Aspire to an existing app
• Aspire AppHost
• PostgreSQL hosting integration
• Redis hosting integration
• JavaScript/Vite hosting integration
• Aspire telemetry
• Aspire architecture and production-runtime boundary