Skip to content

Clarify nightly Aspire dashboard documentation #7379

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lbussell merged 7 commits into from
Oct 8, 2026
Merged

Clarify nightly Aspire dashboard documentation #7379

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
b5c2151
Clarify nightly Aspire dashboard documentation
IEvangelist Sep 28, 2026
4ae1f5e
Keep sole dashboard portal README and fix Markdown formatting
IEvangelist Sep 28, 2026
62a315e
Eject Aspire Dashboard README template
lbussell Oct 1, 2026
c71f4ef
Remove duplicate nightly README variable
lbussell Oct 7, 2026
efa7acb
Ignore flaky Ubuntu CVE index link
lbussell Oct 7, 2026
4e82b9a
Apply Aspire dashboard README review feedback
IEvangelist Oct 8, 2026
66c1564
Align Aspire dashboard README template
IEvangelist Oct 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .github/workflows/check-markdown-links.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,8 @@ jobs:
MLC_IGNORE_MSRC: https://www.microsoft.com/msrc/faqs-report-an-issue,https://www.microsoft.com/msrc/bounty-dot-net-core
# Kubernetes documentation links are unstable
MLC_IGNORE_KUBERNETES: https://kubernetes.io/*,https://k3s.io/*,https://minikube.sigs.k8s.io/*
# Ubuntu's CVE index intermittently returns 504 responses to automated requests
MLC_IGNORE_UBUNTU_CVES: https://ubuntu.com/security/cves
# Some GitHub links redirect to the login page
MLC_REDIRECT_GITHUB: https://github.com/login*
# Sites that redirect locale-neutral URLs to locale-specific URLs
Expand All @@ -43,6 +45,6 @@ jobs:
--gitignore
--root-dir .
--ignore-path eng/announcement-templates,eng/readme-templates
--ignore-links ${{ env.MLC_IGNORE_GITHUB }},${{ env.MLC_IGNORE_SHORT_LINKS }},${{ env.MLC_IGNORE_MSRC }},${{ env.MLC_IGNORE_KUBERNETES }}
--ignore-links ${{ env.MLC_IGNORE_GITHUB }},${{ env.MLC_IGNORE_SHORT_LINKS }},${{ env.MLC_IGNORE_MSRC }},${{ env.MLC_IGNORE_KUBERNETES }},${{ env.MLC_IGNORE_UBUNTU_CVES }}
--do-not-warn-for-redirect-to ${{ env.MLC_REDIRECT_GITHUB }},${{ env.MLC_REDIRECT_LOCALES }}
--throttle 250
142 changes: 31 additions & 111 deletions .portal-docs/mar/README.dashboard.portal.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,146 +1,66 @@
## About

> **Important**: The aspire/nightly/dashboard image is a preview build of the Aspire Dashboard and is not signed. See [aspire/dashboard](https://mcr.microsoft.com/artifact/mar/aspire/dashboard/about) for stable releases.

This image contains the [Aspire Dashboard](https://aspire.dev/dashboard/standalone/), a standalone browser-based app for viewing telemetry and run-time information about distributed applications. The source is available in the [microsoft/aspire](https://github.com/microsoft/aspire) repository.

Watch [discussions](https://github.com/dotnet/dotnet-docker/discussions/categories/announcements) for Docker-related .NET announcements.

## Featured Tags

* `13`
* `docker pull mcr.microsoft.com/aspire/nightly/dashboard:13`

## Related Repositories

.NET:

* [dotnet](https://mcr.microsoft.com/catalog?search=dotnet): .NET
* [dotnet/nightly/sdk](https://mcr.microsoft.com/artifact/mar/dotnet/nightly/sdk/about): .NET SDK (Preview)
* [dotnet/nightly/aspnet](https://mcr.microsoft.com/artifact/mar/dotnet/nightly/aspnet/about): ASP.NET Core Runtime (Preview)
* [dotnet/nightly/runtime](https://mcr.microsoft.com/artifact/mar/dotnet/nightly/runtime/about): .NET Runtime (Preview)
* [dotnet/nightly/runtime-deps](https://mcr.microsoft.com/artifact/mar/dotnet/nightly/runtime-deps/about): .NET Runtime Dependencies (Preview)
* [dotnet/nightly/monitor](https://mcr.microsoft.com/artifact/mar/dotnet/nightly/monitor/about): .NET Monitor Tool (Preview)
* [dotnet/nightly/yarp](https://mcr.microsoft.com/artifact/mar/dotnet/nightly/yarp/about): YARP (Yet Another Reverse Proxy) (Preview)
* [dotnet/samples](https://mcr.microsoft.com/artifact/mar/dotnet/samples/about): .NET Samples

.NET Framework:
## About

* [dotnet/framework](https://mcr.microsoft.com/catalog?search=dotnet/framework): .NET Framework, ASP.NET and WCF
* [dotnet/framework/samples](https://mcr.microsoft.com/artifact/mar/dotnet/framework/samples/about): .NET Framework, ASP.NET and WCF Samples
The [Aspire Dashboard](https://aspire.dev/dashboard/standalone/) is a standalone viewer for logs, traces, and metrics from OpenTelemetry-enabled applications in any language. Source code is available in [microsoft/aspire](https://github.com/microsoft/aspire).

## Usage

The Aspire Dashboard is a browser-based app to view run-time information about your distributed application.

The dashboard shows:

* Resources that make up your app, such as .NET projects, executables and containers.
* Live console logs of resources.
* Live telemetry, such as structured logs, traces and metrics.

### Configuration

The dashboard must be configured when it is started. The configuration is done via environment variables. The following environment variables are supported:

* `ASPNETCORE_URLS` specifies one or more HTTP endpoints through which the dashboard frontend is served. The frontend endpoint is used to view the dashboard in a browser. Defaults to `http://localhost:18888`.
* `DOTNET_DASHBOARD_OTLP_ENDPOINT_URL` specifies the [OTLP/gRPC](https://opentelemetry.io/docs/specs/otlp/#otlpgrpc) endpoint. This endpoint hosts an OTLP service and receives telemetry using gRPC. When the dashboard is launched by the Aspire app host this address is secured with HTTPS. Securing the dashboard with HTTPS is recommended. Defaults to `http://localhost:18889`.
* `DOTNET_DASHBOARD_OTLP_HTTP_ENDPOINT_URL` specifies the [OTLP/HTTP](https://opentelemetry.io/docs/specs/otlp/#otlphttp) endpoint. This endpoint hosts an OTLP service and receives telemetry using Protobuf over HTTP. Defaults to `http://localhost:18890`.
* `ASPIRE_DASHBOARD_MCP_ENDPOINT_URL` specifies the Aspire MCP endpoint. When this value isn't specified then the MCP server is hosted with an `ASPNETCORE_URLS` endpoint. The MCP server can be disabled by configuring `Dashboard:Mcp:Disabled` to `true`. Defaults to `http://localhost:18891`.
* `DOTNET_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS` specifies the dashboard doesn't use authentication and accepts anonymous access. This setting is a shortcut to configuring `Dashboard:Frontend:AuthMode`, `Dashboard:Otlp:AuthMode` and `Dashboard:Mcp:AuthMode` to `Unsecured`.
* `DOTNET_DASHBOARD_CONFIG_FILE_PATH` specifies the path for an optional JSON configuration file.

#### Frontend authentication
Run the dashboard locally:

The dashboard's frontend supports OpenID Connect (OIDC). Set `Dashboard__Frontend__AuthMode` to `OpenIdConnect`, then add the following configuration:
```console
docker run --rm -d --name aspire-dashboard -p 127.0.0.1:18888:18888 -p 127.0.0.1:4317:18889 -p 127.0.0.1:4318:18890 mcr.microsoft.com/aspire/nightly/dashboard:13
```

* `Authentication__Schemes__OpenIdConnect__Authority` — URL to the identity provider (IdP)
* `Authentication__Schemes__OpenIdConnect__ClientId` — Identity of the relying party (RP)
* `Authentication__Schemes__OpenIdConnect__ClientSecret`— A secret that only the real RP would know
* Other properties of [`OpenIdConnectOptions`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.builder.openidconnectoptions) specified in configuration container `Authentication__Schemes__OpenIdConnect__*`
Open `http://localhost:18888`. To sign in, use the login URL or token printed in the container logs:

It may also be run unsecured. Set `Dashboard__Frontend__AuthMode` to `Unsecured`. The frontend endpoint will allow anonymous access. This setting is used during local development, but is not recommended if you attempt to host the dashboard in other settings.
```console
docker logs aspire-dashboard
```

### OTLP authentication
This example keeps browser-token authentication enabled and binds the published ports to the host's loopback interface. Incoming OTLP telemetry is unauthenticated by default in standalone mode; the browser token does not secure telemetry ingestion. Only accept telemetry from trusted applications; configure HTTPS, authentication, and network controls before exposing the dashboard beyond your machine. See [dashboard security guidance](https://aspire.dev/dashboard/security-considerations/).

The OTLP endpoint can be secured with [client certificate](https://learn.microsoft.com/aspnet/core/security/authentication/certauth) or API key authentication.
### Send telemetry

For client certification authentication, set `Dashboard__Otlp__AuthMode` to `Certificate`.
Instrument your application with its language's OpenTelemetry SDK and configure an OTLP exporter with the matching protocol and endpoint. Starting the dashboard does not instrument your application automatically. For applications running on the host, use:

For API key authentication, set `Dashboard__Otlp__AuthMode` to `ApiKey`, then add the following configuration:
* OTLP/gRPC: `http://localhost:4317` (mapped to container port `18889`).
* OTLP/HTTP: `http://localhost:4318` (mapped to container port `18890`).

* `Dashboard__Otlp__PrimaryApiKey` specifies the primary API key. (required, string)
* `Dashboard__Otlp__SecondaryApiKey` specifies the secondary API key. (optional, string)
For applications in other containers, use the dashboard container's name and port (`18889` or `18890`) on a shared Docker network, not their own `localhost`.

It may also be run unsecured. Set `Dashboard__Otlp__AuthMode` to `Unsecured`. The OTLP endpoint will allow anonymous access. This setting is used during local development, but is not recommended if you attempt to host the dashboard in other settings.
### Operational notes

### Resources
* Telemetry is stored in memory with configurable limits and is lost when the dashboard restarts. The dashboard is intended for development and short-term diagnostics, not durable telemetry storage.
* Standalone mode displays telemetry without an AppHost. Resource listings and captured console logs require a configured [resource service](https://aspire.dev/dashboard/configuration/#resources).

* `Dashboard__ResourceServiceClient__Url` specifies the gRPC endpoint to which the dashboard connects for its data. There's no default. If this variable is unspecified, the dashboard shows OTEL data but no resource list or console logs.
### Documentation and examples

The resource service client supports certificates. Set `Dashboard__ResourceServiceClient__AuthMode` to `Certificate`, then add the following configuration:

* `Dashboard__ResourceServiceClient__ClientCertificate__Source` (required) one of:
* `File` to load the cert from a file path, configured with:
* `Dashboard__ResourceServiceClient__ClientCertificate__FilePath` (required, string)
* `Dashboard__ResourceServiceClient__ClientCertificate__Password` (optional, string)
* `KeyStore` to load the cert from a key store, configured with:
* `Dashboard__ResourceServiceClient__ClientCertificate__Subject` (required, string)
* `Dashboard__ResourceServiceClient__ClientCertificate__Store` (optional, [`StoreName`](https://learn.microsoft.com/dotnet/api/system.security.cryptography.x509certificates.storename), defaults to `My`)
* `Dashboard__ResourceServiceClient__ClientCertificate__Location` (optional, [`StoreLocation`](https://learn.microsoft.com/dotnet/api/system.security.cryptography.x509certificates.storelocation), defaults to `CurrentUser`)

To opt-out of authentication, set `Dashboard__ResourceServiceClient__AuthMode` to `Unsecured`. This completely disables all security for the resource service client. This setting is used during local development, but is not recommended if you attempt to host the dashboard in other settings.

#### Telemetry Limits

Telemetry is stored in-memory. To avoid excessive memory usage, the dashboard has limits on the count and size of stored telemetry. When a count limit is reached, new telemetry is added, and the oldest telemetry is removed. When a size limit is reached, data is truncated to the limit.

* `Dashboard__TelemetryLimits__MaxLogCount` specifies the maximum number of log entries. Defaults to 10,000.
* `Dashboard__TelemetryLimits__MaxTraceCount` specifies the maximum number of traces. Defaults to 10,000.
* `Dashboard__TelemetryLimits__MaxMetricsCount` specifies the maximum number of metric data points. Defaults to 50,000.
* `Dashboard__TelemetryLimits__MaxAttributeCount` specifies the maximum number of attributes on telemetry. Defaults to 128.
* `Dashboard__TelemetryLimits__MaxAttributeLength` specifies the maximum length of attributes. Defaults to unlimited.
* `Dashboard__TelemetryLimits__MaxSpanEventCount` specifies the maximum number of events on span attributes. Defaults to unlimited.

Limits are per-resource. For example, a `MaxLogCount` value of 10,000 configures the dashboard to store up to 10,000 log entries per-resource.

### Other

* `Dashboard__ApplicationName` specifies the application name to be displayed in the UI. This applies only when no resource service URL is specified. When a resource service exists, the service specifies the application name.
* [Run the standalone dashboard](https://aspire.dev/dashboard/standalone/).
* [Python telemetry tutorial](https://aspire.dev/dashboard/standalone-for-python/).
* [JavaScript and Node.js telemetry tutorial](https://aspire.dev/dashboard/standalone-for-nodejs/).
* [Standalone dashboard sample (C#)](https://github.com/microsoft/aspire-samples/tree/main/samples/standalone-dashboard).
* [Dashboard configuration reference](https://aspire.dev/dashboard/configuration/).

## Support

### Lifecycle

* [Microsoft Support for Aspire](https://aspire.dev/support/)
* [Supported Container Platforms Policy](https://github.com/dotnet/dotnet-docker/blob/main/documentation/supported-platforms.md)
* [Supported Tags Policy](https://github.com/dotnet/dotnet-docker/blob/main/documentation/supported-tags.md)

### Image Update Policy

* **Base Image Updates:** Images are re-built within 12 hours of any updates to their base images (e.g. debian:bookworm-slim, windows/nanoserver:ltsc2022, etc.).
* **.NET Releases:** Images are re-built as part of releasing new .NET versions. This includes new major versions, minor versions, and servicing releases.
* **Critical CVEs:** Images are re-built to pick up critical CVE fixes as described by the CVE Update Policy below.
* **Monthly Re-builds:** Images are re-built monthly, typically on the second Tuesday of the month, in order to pick up lower-severity CVE fixes.
* **Out-Of-Band Updates:** Images can sometimes be re-built when out-of-band updates are necessary to address critical issues. If this happens, new fixed version tags will be updated according to the [Fixed version tags documentation](https://github.com/dotnet/dotnet-docker/blob/main/documentation/supported-tags.md#fixed-version-tags).

#### CVE Update Policy

.NET container images are regularly monitored for the presence of CVEs. A given image will be rebuilt to pick up fixes for a CVE when:

* We detect the image contains a CVE with a [CVSS](https://nvd.nist.gov/vuln-metrics/cvss) score of "Critical"
* **AND** the CVE is in a package that is added in our Dockerfile layers (meaning the CVE is in a package we explicitly install or any transitive dependencies of those packages)
* **AND** there is a CVE fix for the package available in the affected base image's package repository.
See the [Aspire support policy](https://aspire.dev/support/) for supported versions and lifecycle information. Container images are also covered by the [Supported Container Platforms Policy](https://github.com/dotnet/dotnet-docker/blob/main/documentation/supported-platforms.md), [Supported Tags Policy](https://github.com/dotnet/dotnet-docker/blob/main/documentation/supported-tags.md), and [Image Update Policy](https://github.com/dotnet/dotnet-docker/blob/main/README.md#image-update-policy).

Please refer to the [Security Policy](https://github.com/dotnet/dotnet-docker/blob/main/SECURITY.md) and [Container Vulnerability Workflow](https://github.com/dotnet/dotnet-docker/blob/main/documentation/vulnerability-reporting.md) for more detail about what to do when a CVE is encountered in a .NET image.
For container security and vulnerability reporting, see the [Security Policy](https://github.com/dotnet/dotnet-docker/blob/main/SECURITY.md) and [Container Vulnerability Workflow](https://github.com/dotnet/dotnet-docker/blob/main/documentation/vulnerability-reporting.md). Additional security information can be found on [aspire.dev/dashboard/security-considerations](https://aspire.dev/dashboard/security-considerations/#standalone-mode).

### Feedback

* [File an issue](https://github.com/dotnet/dotnet-docker/issues/new/choose)
* [Contact Microsoft Support](https://support.microsoft.com/contactus/)
* [Dashboard issues and feature requests](https://github.com/microsoft/aspire/issues).
* [Container image issues](https://github.com/dotnet/dotnet-docker/issues/new/choose).
* [Contact Microsoft Support](https://support.microsoft.com/contactus/).

## License

* Legal Notice: [Container License Information](https://aka.ms/mcr/osslegalnotice)
* [.NET license](https://github.com/dotnet/dotnet-docker/blob/main/LICENSE)
* [Aspire MIT license](https://github.com/microsoft/aspire/blob/main/LICENSE.TXT)
* [Discover licensing for Linux image contents](https://github.com/dotnet/dotnet-docker/blob/main/documentation/image-artifact-details.md)
Loading
Loading