Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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: 4 additions & 0 deletions src/frontend/config/sidebar/deployment.topics.ts
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,10 @@ export const deploymentTopics: StarlightSidebarTopicsUserConfig = {
label: 'Docker Compose',
slug: 'deployment/docker-compose',
},
{
label: 'Radius',
slug: 'deployment/radius',
},
{
label: 'Kubernetes',
collapsed: false,
Expand Down
4 changes: 4 additions & 0 deletions src/frontend/config/sidebar/integrations.topics.ts
Original file line number Diff line number Diff line change
Expand Up @@ -315,6 +315,10 @@ export const integrationTopics: StarlightSidebarTopicsUserConfig = {
label: 'Configure Azure Container Apps',
slug: 'integrations/cloud/azure/configure-container-apps',
},
{
label: 'Azure Connector Namespace',
slug: 'integrations/cloud/azure/azure-connector-namespace',
},
{
label: 'Default Azure credential',
slug: 'integrations/cloud/azure/azure-default-credential',
Expand Down
28 changes: 21 additions & 7 deletions src/frontend/src/content/docs/app-host/typescript-apphost.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -292,14 +292,15 @@ The Aspire CLI supports the following package managers at the **AppHost root**
| pnpm | `packageManager` or `pnpm-lock.yaml` | pnpm 10 or later |
| Yarn | `packageManager`, `yarn.lock`, `.yarnrc.yml`, or `.yarn/` | Yarn 4 or later (Berry) |
| Bun | `packageManager`, `bun.lock`, or `bun.lockb` | Bun 1.2 or later |
| Deno | `packageManager`, `deno.lock`, `deno.json`, or `deno.jsonc` | Deno 2 or later |
| Yarn Classic (v1) | `yarn.lock` with `# yarn lockfile v1` or `packageManager` with `yarn@1.x` | Not supported |

This policy governs the **AppHost root only**. Apps the AppHost orchestrates — for example, a Node.js service added with `addNodeApp`, a Bun guest app, or a workspace package — can use any package manager their own tooling requires; they are independent of the AppHost-root toolchain.

Aspire end-to-end tests cover TypeScript AppHosts with representative `packageManager` pins such as `npm@10.0.0`, `pnpm@10.0.0`, `yarn@4.14.1`, and `bun@1.2.0`. These tested versions are representative points within the supported ranges, not the only versions you can use.

<Aside type="caution">
**Yarn Classic (v1) is not supported.** If the Aspire CLI detects a Yarn Classic lock file (`# yarn lockfile v1`) or a `packageManager` field such as `"yarn@1.x"` in `package.json`, it throws an error and stops. Upgrade to Yarn 4 or later, or switch to npm, pnpm, or Bun.
**Yarn Classic (v1) is not supported.** If the Aspire CLI detects a Yarn Classic lock file (`# yarn lockfile v1`) or a `packageManager` field such as `"yarn@1.x"` in `package.json`, it throws an error and stops. Upgrade to Yarn 4 or later, or switch to npm, pnpm, Bun, or Deno.

To upgrade to Yarn 4, run:

Expand Down Expand Up @@ -338,7 +339,7 @@ The `dev` script means you can also start your AppHost with `npm run dev` (or th

### Supported Node.js engine

TypeScript AppHosts target the Node.js engine range that `aspire init` writes into the scaffolded AppHost `package.json`:
When using Node.js, TypeScript AppHosts target the engine range that `aspire init` writes into the scaffolded AppHost `package.json`. Deno and Bun run the AppHost with their own runtimes:

```json title="package.json — supported engines.node"
{
Expand All @@ -362,7 +363,7 @@ If you widen `engines.node` beyond the scaffolded constraint, you take on respon

## Package manager toolchain

The Aspire CLI automatically detects which Node-compatible package manager your project uses and adjusts install and run commands accordingly. The following toolchains are supported: **npm** (default), **Bun**, **Yarn**, and **pnpm**.
The Aspire CLI automatically detects your TypeScript AppHost toolchain and adjusts install and run commands accordingly. The following toolchains are supported: **npm** (default), **Bun**, **Yarn**, **pnpm**, and **Deno**.

### Toolchain detection

Expand All @@ -371,7 +372,7 @@ Detection follows the [supported AppHost-root package managers](#package-manager
<Steps>

1. The `packageManager` field in `package.json` — for example, `"packageManager": "pnpm@10.0.0"`.
2. Lockfiles: `bun.lock` or `bun.lockb` → Bun; `pnpm-lock.yaml` → pnpm; `yarn.lock`, `.yarnrc.yml`, or a `.yarn/` directory → Yarn.
2. Toolchain markers: `bun.lock` or `bun.lockb` → Bun; `pnpm-lock.yaml` → pnpm; `yarn.lock`, `.yarnrc.yml`, or a `.yarn/` directory → Yarn; `deno.lock`, `deno.json`, or `deno.jsonc` → Deno.
3. If nothing is found, npm is used as the default.

</Steps>
Expand Down Expand Up @@ -447,14 +448,25 @@ When a non-npm toolchain is detected, the CLI substitutes the matching commands:
| pnpm | `pnpm install` | `pnpm exec tsx ...` | `pnpm exec nodemon ...` |
| Yarn | `yarn install` | `yarn exec tsx ...` | `yarn exec nodemon ...` |
| Bun | `bun install` | `bun run {appHostFile}` | `bun --watch run {appHostFile}` |
| Deno | `deno install` | `deno run -A --unstable-sloppy-imports {appHostFile}` | `deno run -A --unstable-sloppy-imports --check --watch {appHostFile}` |

:::note
Bun has built-in TypeScript support, so it runs `apphost.mts` directly without `tsx`.
:::

### Use Deno as the AppHost runtime

Install Deno 2 or later and select it with a Deno configuration file, lockfile, or a `packageManager` entry such as `"deno@2.0.0"`. The generated AppHost module and resource APIs stay the same. This is distinct from [hosting a Deno application](/integrations/frameworks/deno/deno-host/): `addDenoApp` models a guest resource and doesn't choose the AppHost runtime.

Aspire restores dependencies with `deno install` and validates the AppHost with `deno check`. Deno uses its own configuration rather than `tsconfig.apphost.json`. Watch mode uses Deno's native watcher and checks types on every restart, without `tsx` or `nodemon`. The CLI rejects Deno 1.x.

:::caution[AppHost permissions]
Aspire starts a Deno AppHost with `--allow-all` because the AppHost needs environment, filesystem, network, and process access to orchestrate resources. This isn't a Deno sandbox: run only AppHost code and integrations you trust.
:::

### aspire doctor checks

The `aspire doctor` command checks that the required JavaScript toolchain executable is available. If Bun, Yarn, or pnpm is detected but not installed, the command reports an error with install guidance.
The `aspire doctor` command checks that the selected toolchain executable is available. If Bun, Yarn, pnpm, or Deno is detected but not installed, the command reports an error with install guidance. For Deno, it also checks the Deno 2 minimum version.

```bash title="Aspire CLI"
aspire doctor
Expand Down Expand Up @@ -488,15 +500,15 @@ The thenable wrappers are generated automatically — you do not need to change

## TypeScript validation before startup

Before starting a TypeScript AppHost, the Aspire CLI runs `tsc --noEmit` to check for type errors to prevent the dashboard and resources from starting in a partially broken state. If your AppHost has TypeScript compile errors, `aspire run` and `aspire publish` stop before the AppHost launches and display the diagnostic output:
Before starting a TypeScript AppHost, the Aspire CLI runs `tsc --noEmit`, or `deno check` for Deno, to check for type errors to prevent the dashboard and resources from starting in a partially broken state. If your AppHost has TypeScript compile errors, `aspire run` and `aspire publish` stop before the AppHost launches and display the diagnostic output:

```text
apphost.mts(22,7): error TS2322: Type 'string' is not assignable to type 'number'.
```

### Watch mode behavior

When you use `aspire run` in watch mode, the TypeScript validation is embedded in the nodemon restart command. The watcher **can still start** even if there are initial type errors — it will recover automatically as you edit and save files that fix the errors.
When you use `aspire run` in watch mode with a nodemon-based toolchain, TypeScript validation is embedded in the restart command. The watcher **can still start** even if there are initial type errors — it will recover automatically as you edit and save files that fix the errors. Deno instead uses its native `--watch --check` flow.

## HTTPS development certificates

Expand Down Expand Up @@ -537,6 +549,8 @@ When your AppHost code opens TLS connections to Aspire-managed resources at runt

If you've already set `NODE_EXTRA_CA_CERTS` for your own certificates, the CLI preserves your value by generating a combined bundle that includes both your certificates and the Aspire development certificate, rather than overwriting your setting.

For a Deno AppHost, Aspire uses `DENO_CERT` for the trusted PEM bundle, preserving an existing bundle by combining it with Aspire's development certificate. This works across Deno 2 releases; `NODE_EXTRA_CA_CERTS` support in Deno starts only with Deno 2.8.

<LearnMore>
See [Certificate configuration](/app-host/certificate-configuration/) for details
on HTTPS certificate management in Aspire, including Linux-specific setup.
Expand Down
8 changes: 1 addition & 7 deletions src/frontend/src/content/docs/app-host/with-terminal.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -227,13 +227,7 @@ The **Open terminal** context-menu item is only visible for resources that have

## Work with terminals from the CLI

The `aspire terminal` command group lets you list and attach to terminal sessions from your shell. Because `WithTerminal` is experimental, these commands are hidden behind a feature flag. Enable them with:

```bash title="Enable the aspire terminal commands"
aspire config set features.terminalCommandsEnabled true
```

Then:
The `aspire terminal` command group lets you list and attach to terminal sessions from your shell without any configuration step:

- [`aspire terminal ps`](/reference/cli/commands/aspire-terminal-ps/) lists every terminal-enabled resource in the running AppHost, with grid size, attached-peer count, and per-replica health.
- [`aspire terminal attach`](/reference/cli/commands/aspire-terminal-attach/) attaches your local terminal to a resource's interactive PTY session.
Expand Down
2 changes: 1 addition & 1 deletion src/frontend/src/content/docs/dashboard/configuration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -316,7 +316,7 @@ Telemetry limits have different scopes depending upon the telemetry type:

| Option | Description |
|--------|-------------|
| `Dashboard:ApplicationName`<br/>Default: `Aspire` | The logical application name used to partition persisted data. The AppHost supplies its application name automatically. Set it with the `ASPIRE_DASHBOARD_APPLICATION_NAME` environment variable. |
| `Dashboard:ApplicationName`<br/>Default: `Aspire` | The logical application name used to partition persisted data and to scope authentication and antiforgery cookie names. The AppHost supplies its application name automatically. Set it with the `ASPIRE_DASHBOARD_APPLICATION_NAME` environment variable. Configure a distinct name for dashboards whose cookies should be kept separate; see [Cookie scoping by application name](/dashboard/security-considerations/#cookie-scoping-by-application-name). |
| `Dashboard:UI:DisableResourceGraph`<br/>Default: `false` | Disables displaying the resource graph UI in the dashboard. |
| `Dashboard:UI:DisableImport`<br/>Default: `false` | Disables the telemetry import UI in the dashboard. |
| `Dashboard:UI:DisableAgentHelp`<br/>Default: `false` | Disables the **AI Agents** button in the dashboard header. When `false`, a button is shown in the header that opens a dialog with instructions for using AI coding agents with the dashboard. |
Expand Down
7 changes: 7 additions & 0 deletions src/frontend/src/content/docs/dashboard/explore.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -135,6 +135,8 @@ In the upcoming sections, you discover how to create an Aspire project and embar

The screenshots and animations follow the site's light or dark theme. For more information about changing the dashboard itself, see [Theme selection](#theme-selection).

The Aspire dashboard is compiled with Native AOT and uses Fluent UI v5. The normal AppHost and CLI workflows select the packaged dashboard automatically, without additional application telemetry configuration.

## Dashboard authentication

When you run an Aspire AppHost, the orchestrator starts up all the app's dependent resources and then opens a browser window to the dashboard. The Aspire dashboard requires token-based authentication for its users because it displays environment variables and other sensitive information.
Expand Down Expand Up @@ -180,6 +182,8 @@ You can also obtain the login token from the container logs. For more informatio

## Resources page

Management integrations such as pgAdmin, pgweb, phpMyAdmin, Kafka UI, Mongo Express, and Attu hide their management containers and expose **Manage** links on the resources they administer. These links appear ahead of other resource URLs. Built-in management endpoints, including RabbitMQ and Qdrant, also use the **Manage** label.

The **Resources** page is the default home page of the Aspire dashboard. This page lists all of the projects, containers, and executables included in your Aspire solution. For example, the starter application includes two projects:

- **apiservice**: A backend API project built using Minimal APIs.
Expand Down Expand Up @@ -374,6 +378,8 @@ AppHosts can also create their own terminals for development and setup workflows

AppHost-owned dock terminals are separate from resource terminals configured with `WithTerminal`. For an interactive setup workflow, see [Terminal interactions](/extensibility/interaction-service/#terminal-interactions).

Open the empty terminal dock using the dashboard's terminal button or the <Kbd windows="`" mac="`" linux="`" /> key. It shows **No docked terminals**, a **More information** link to this documentation, and a hint to press <Kbd windows="`" mac="`" linux="`" /> again to hide the panel.

### Structured logs page

Aspire automatically configures your projects with logging using OpenTelemetry. Navigate to the **Structured logs** page to view the semantic logs for your Aspire project. [Semantic, or structured logging](https://github.com/NLog/NLog/wiki/How-to-use-structured-logging) makes it easier to store and query log-events, as the log-event message-template and message-parameters are preserved, instead of just transforming them into a formatted message. You notice a clean structure for the different logs displayed on the page using columns:
Expand Down Expand Up @@ -655,6 +661,7 @@ Open the selector to browse runs for the Aspire app:
- Select a completed run by its start time to inspect its saved data. Historical runs are read-only, but the dashboard continues to save data for the live run while you view them. Select **Live run** to return to the current run.
- The dashboard keeps up to 10 unpinned runs per app. After a new run starts, the oldest unpinned runs beyond that limit are cleaned up.
- Runs can be pinned to prevent them from being cleaned up. Hover over a run and select its pin icon. Pinned runs don't count toward the limit and appear above unpinned runs in the list. Select the icon again to unpin the run.
- Pinning or unpinning a run keeps the selector open and preserves your current run selection, even though the item moves to its updated sort position in the list.

<ThemeImage dark={dashboardRunSelectorExpanded} light={dashboardRunSelectorExpanded} alt="Expanded Aspire dashboard run selector showing the live run and a pinned historical run." />

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,26 @@ aspire dashboard run --allow-anonymous --AllowedHosts='localhost;dashboard.examp
Anyone who can reach an anonymously accessible dashboard can view potentially sensitive resource and telemetry data without authentication. Untrusted apps can also send telemetry to an unsecured OTLP endpoint. Only allow anonymous access in trusted local development environments, and don't expose an anonymously accessible dashboard or its endpoints to an untrusted network.
:::

## Cookie scoping by application name

Browser cookies are shared across ports on the same hostname. Without a distinguishing name, dashboards running on different ports of the same host, such as `localhost`, would use the same authentication and antiforgery cookie names and could interfere with each other, for example by signing one dashboard out when you sign in to another.

To avoid this, the dashboard's browser-token and OpenID Connect authentication cookies, and its antiforgery cookie, include a suffix derived from `Dashboard:ApplicationName`. The suffix combines a lowercase, cookie-safe prefix of up to 32 characters with a hash of the full application name. For example, an application name of `My application` produces cookie names such as `.Aspire.Dashboard.Auth.my-application-<hash>` and `.Aspire.Dashboard.Antiforgery.my-application-<hash>`. Dashboards configured with the same application name use the same cookie names and can still collide; this doesn't guarantee that one dashboard can decrypt or accept another's authentication cookie.

Configure a distinct `Dashboard:ApplicationName` for each dashboard whose cookies should be kept separate:

```json title="Dashboard application settings"
{
"Dashboard": {
"ApplicationName": "My application"
}
}
```

Application-name cookie scoping avoids accidental collisions between dashboards; it isn't a security boundary, and the hash used to build the suffix is a non-cryptographic naming hash, not an authentication or integrity mechanism.

Changing `Dashboard:ApplicationName` changes the cookie names, so existing browser sessions aren't migrated: you'll need to sign in again after the name changes. Other browser preferences that don't need to be application-specific, such as time format, can still be shared across dashboards that use the same browser origin. Collapsed-resource state in local storage follows the application name reported by the connected resource service, which can differ from the configured `Dashboard:ApplicationName` used for cookies and disk persistence; see [Storage layout](/dashboard/data-persistence/#storage-layout) for how persisted data is scoped by application name.

## Secure telemetry endpoint

The Aspire dashboard provides a variety of ways to view logs, traces, and metrics for your app. This information enables you to track the behavior and performance of your app and to diagnose any issues that arise. It's important that you can trust this information, and a warning is displayed in the dashboard UI if telemetry isn't secured.
Expand Down
2 changes: 2 additions & 0 deletions src/frontend/src/content/docs/dashboard/standalone.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@ You can start the dashboard in two ways:

Both options receive telemetry from OpenTelemetry-enabled apps. Instrumentation and export configuration are required in each application; starting the dashboard doesn't instrument your code. For language-specific setup, see [Python telemetry](/dashboard/standalone-for-python/) or [JavaScript and Node.js telemetry](/dashboard/standalone-for-nodejs/).

The dashboard is compiled with Native AOT and uses Fluent UI v5. Normal CLI and AppHost startup select the packaged dashboard automatically; you don't need an AOT switch or a separate telemetry configuration. Use the supported dashboard image for container-based deployments. OTLP endpoints, authentication requirements, and persistence settings apply regardless of how you start the dashboard.

<ThemeImage
light={standaloneModeImageLight}
dark={standaloneModeImage}
Expand Down
Loading
Loading