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
68 changes: 35 additions & 33 deletions src/frontend/src/content/docs/get-started/dev-containers.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -15,17 +15,15 @@ import vscodeRunButton from '@assets/get-started/vscode-run-button.png';
import browserCertError from '@assets/get-started/browser-certificate-error.png';
import aspireDashboard from '@assets/get-started/aspire-dashboard-in-devcontainer.png';

The [Dev Containers Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) provides a way for development teams to develop within a containerized environment where all dependencies are preconfigured. With Aspire 9.1, there's added logic to better support working with Aspire within a Dev Container environment by automatically configuring port forwarding.

Before Aspire 9.1, it was possible to use Aspire within a Dev Container, however more manual configuration was required.
The [Dev Containers Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) provides a way for development teams to work inside a containerized environment where dependencies are defined as part of the repository. Aspire automatically configures forwarded ports in Dev Containers so the dashboard and resource endpoints are easier to open from Visual Studio Code.

## Dev Containers vs. GitHub Codespaces

Using Dev Containers in Visual Studio Code is similar to using GitHub Codespaces. With the release of Aspire 9.1, support for both Dev Containers in Visual Studio Code and GitHub Codespaces was enhanced. Although the experiences are similar, there are some differences. For more information on using Aspire with GitHub Codespaces, see [Aspire and GitHub Codespaces](/get-started/github-codespaces/).
Using Dev Containers in Visual Studio Code is similar to using GitHub Codespaces. Although the experiences are similar, there are some differences. For more information on using Aspire with GitHub Codespaces, see [Aspire and GitHub Codespaces](/get-started/github-codespaces/).

## Quick start using template repository

To configure Dev Containers in Visual Studio Code, use the `.devcontainer/devcontainer.json` file in your repository. The simplest way to get started is by creating a new repository from our [template repository](https://github.com/microsoft/aspire-devcontainer). Consider the following steps:
To configure Dev Containers in Visual Studio Code, use the `.devcontainer/devcontainer.json` file in your repository. The simplest way to get started is by creating a new repository from the [Aspire Dev Container template](https://github.com/dotnet/aspire-devcontainer). Consider the following steps:

<Steps>

Expand All @@ -52,18 +50,18 @@ To configure Dev Containers in Visual Studio Code, use the `.devcontainer/devcon
alt="Screenshot showing VS Code prompt to open the repository inside a container."
/>

After a few moments, the list of files become visible and the local build of the dev container will be completed.
After a few moments, the files become visible and the Dev Container finishes setting up. The template installs the Aspire CLI during setup, so you can create an app immediately without manually installing `Aspire.ProjectTemplates`.

<Image
src={devcontainerBuildCompleted}
alt="Screenshot showing the dev container build completed notification in VS Code."
/>

1. Open a new terminal window in Visual Studio Code (<Kbd windows='Ctrl+Shift+\' mac='Cmd+Shift+\' />) and create a new Aspire project using the Aspire CLI.
1. Open a new terminal window in Visual Studio Code (<Kbd windows='Ctrl+Shift+\\' mac='Cmd+Shift+\\' />) and create a new Aspire project using the Aspire CLI.

```bash
aspire new aspire-starter -n HelloAspire
```
```bash title="Aspire CLI — Create an Aspire starter app"
aspire new aspire-starter --name HelloAspire
```

After a few moments, the project will be created and initial dependencies restored.

Expand All @@ -88,7 +86,7 @@ To configure Dev Containers in Visual Studio Code, use the `.devcontainer/devcon
alt="Screenshot of the Aspire dashboard running successfully in the Dev Container."
/>

Aspire automatically configures forwarded ports so that when you select on the endpoints in the Aspire dashboard they're tunneled to processes and nested containers within the Dev Container.
Aspire automatically configures forwarded ports so that when you select the endpoints in the Aspire dashboard they're tunneled to processes and nested containers within the Dev Container.

1. Commit changes to the GitHub repository.

Expand All @@ -98,14 +96,18 @@ To configure Dev Containers in Visual Studio Code, use the `.devcontainer/devcon

## Manually configuring devcontainer.json

The preceding walkthrough demonstrates the streamlined process of creating a Dev Container using the Aspire Dev Container template. If you already have an existing repository and wish to utilize Dev Container functionality with Aspire, add a `devcontainer.json` file to the `.devcontainer` folder within your repository:
The preceding walkthrough demonstrates the streamlined process of creating a Dev Container using the Aspire Dev Container template. If you already have an existing repository and want to use Dev Containers with Aspire, add a `devcontainer.json` file to the `.devcontainer` folder within your repository:

<FileTree>
- .devcontainer
- devcontainer.json
</FileTree>

The [template repository](https://github.com/microsoft/aspire-devcontainer) contains a copy of the `devcontainer.json` file that you can use as a starting point, which should be sufficient for Aspire.
The [template repository](https://github.com/dotnet/aspire-devcontainer) contains a copy of the `devcontainer.json` file that you can use as a starting point, which should be sufficient for Aspire.

:::note
Install the Aspire CLI during container creation so `aspire new` is ready to use as soon as the container finishes building.
:::

## Dev Container scenarios

Expand All @@ -115,11 +117,11 @@ The basic Aspire Dev Container template works well for simple scenarios, but you

For simple Aspire projects that only use .NET project resources without external containers or complex orchestration, you can use a minimal Dev Container configuration:

```json
```json title="JSON — .devcontainer/devcontainer.json"
{
"name": "Aspire - Simple",
"image": "mcr.microsoft.com/devcontainers/dotnet:9.0-bookworm",
"onCreateCommand": "dotnet new install Aspire.ProjectTemplates --force",
"image": "mcr.microsoft.com/devcontainers/dotnet:dev-10.0-noble",
"onCreateCommand": "curl -sSL https://aspire.dev/install.sh | bash",
"postStartCommand": "dotnet dev-certs https --trust",
"customizations": {
"vscode": {
Expand All @@ -135,16 +137,16 @@ This minimal configuration is suitable for Aspire apps that orchestrate only .NE

If your Aspire app includes Node.js resources, add the Node.js feature to your Dev Container:

```json
```json title="JSON — .devcontainer/devcontainer.json"
{
"name": "Aspire with Node.js",
"image": "mcr.microsoft.com/devcontainers/dotnet:9.0-bookworm",
"image": "mcr.microsoft.com/devcontainers/dotnet:dev-10.0-noble",
"features": {
"ghcr.io/devcontainers/features/node:1": {
"version": "lts"
}
},
"onCreateCommand": "dotnet new install Aspire.ProjectTemplates --force",
"onCreateCommand": "curl -sSL https://aspire.dev/install.sh | bash",
"postStartCommand": "dotnet dev-certs https --trust",
"customizations": {
"vscode": {
Expand All @@ -163,10 +165,10 @@ This configuration provides both .NET and Node.js development capabilities withi

When your Aspire app orchestrates container resources, you need Docker-in-Docker (DinD) support. Here's a basic configuration:

```json
```json title="JSON — .devcontainer/devcontainer.json"
{
"name": "Aspire with Containers",
"image": "mcr.microsoft.com/devcontainers/dotnet:9.0-bookworm",
"image": "mcr.microsoft.com/devcontainers/dotnet:dev-10.0-noble",
"features": {
"ghcr.io/devcontainers/features/docker-in-docker:2": {
"version": "latest",
Expand All @@ -179,7 +181,7 @@ When your Aspire app orchestrates container resources, you need Docker-in-Docker
"memory": "16gb",
"storage": "32gb"
},
"onCreateCommand": "dotnet new install Aspire.ProjectTemplates --force",
"onCreateCommand": "curl -sSL https://aspire.dev/install.sh | bash",
"postStartCommand": "dotnet dev-certs https --trust",
"customizations": {
"vscode": {
Expand All @@ -193,10 +195,10 @@ When your Aspire app orchestrates container resources, you need Docker-in-Docker

If you encounter networking issues between containers or need IPv6 support, you can add additional network configuration:

```json
```json title="JSON — .devcontainer/devcontainer.json"
{
"name": "Aspire with Advanced Networking",
"image": "mcr.microsoft.com/devcontainers/dotnet:9.0-bookworm",
"image": "mcr.microsoft.com/devcontainers/dotnet:dev-10.0-noble",
"features": {
"ghcr.io/devcontainers/features/docker-in-docker:2": {
"version": "latest",
Expand All @@ -217,7 +219,7 @@ If you encounter networking issues between containers or need IPv6 support, you
"memory": "32gb",
"storage": "64gb"
},
"onCreateCommand": "dotnet new install Aspire.ProjectTemplates --force",
"onCreateCommand": "curl -sSL https://aspire.dev/install.sh | bash",
"postStartCommand": "dotnet dev-certs https --trust",
"customizations": {
"vscode": {
Expand All @@ -241,17 +243,17 @@ For Aspire apps that integrate with Dapr, you can set up Dapr components in your

#### Basic Dapr setup

```json
```json title="JSON — .devcontainer/devcontainer.json"
{
"name": "Aspire with Dapr",
"image": "mcr.microsoft.com/devcontainers/dotnet:9.0-bookworm",
"image": "mcr.microsoft.com/devcontainers/dotnet:dev-10.0-noble",
"features": {
"ghcr.io/devcontainers/features/docker-in-docker:2": {
"enableNonRootDocker": true
},
"ghcr.io/dapr/cli/dapr-cli:0": {}
},
"onCreateCommand": "dotnet new install Aspire.ProjectTemplates --force",
"onCreateCommand": "curl -sSL https://aspire.dev/install.sh | bash",
"postCreateCommand": "dotnet dev-certs https --trust && dapr init",
"customizations": {
"vscode": {
Expand All @@ -265,18 +267,18 @@ For Aspire apps that integrate with Dapr, you can set up Dapr components in your

For more complex Dapr scenarios that use external backends (Redis, PostgreSQL), you can use Docker Compose:

```json
```json title="JSON — .devcontainer/devcontainer.json"
{
"name": "Aspire with Dapr and Backends",
"image": "mcr.microsoft.com/devcontainers/dotnet:9.0-bookworm",
"image": "mcr.microsoft.com/devcontainers/dotnet:dev-10.0-noble",
"features": {
"ghcr.io/devcontainers/features/docker-in-docker:2": {
"enableNonRootDocker": true
},
"ghcr.io/dapr/cli/dapr-cli:0": {}
},
"runArgs": ["--sysctl", "net.ipv6.conf.all.disable_ipv6=0"],
"onCreateCommand": "dotnet new install Aspire.ProjectTemplates --force",
"onCreateCommand": "curl -sSL https://aspire.dev/install.sh | bash",
"postCreateCommand": [
"dotnet dev-certs https --trust",
"docker compose up -d",
Expand Down Expand Up @@ -307,7 +309,7 @@ When using Dev Containers with Aspire, keep the following considerations in mind
**Networking**

- IPv6 configuration may be required for container-to-container communication.
- Port forwarding is automatically handled by Aspire 9.1 and later versions.
- Port forwarding is automatically handled by Aspire.
- External service connectivity depends on your container runtime configuration.

**Performance**
Expand All @@ -319,5 +321,5 @@ When using Dev Containers with Aspire, keep the following considerations in mind
**Security**

- Dev Containers run with elevated privileges when using Docker-in-Docker.
- SSL certificate trust is handled automatically in most scenarios.
- The development certificate is created and trusted in the container, but your browser might still show a warning the first time you open a forwarded HTTPS endpoint from the host.
- Consider security implications when exposing ports in cloud environments.
58 changes: 45 additions & 13 deletions src/frontend/src/content/docs/get-started/github-codespaces.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -16,20 +16,18 @@ import launchAppHost from '@assets/get-started/codespace-launch-apphost.png';
import debugConsole from '@assets/get-started/codespaces-debug-console.png';
import translatedUrls from '@assets/get-started/codespaces-translated-urls.png';

[GitHub Codespaces](https://github.com/features/codespaces) offers a cloud-hosted development environment based on Visual Studio Code. It can be accessed directly from a web browser or through Visual Studio Code locally, where Visual Studio Code acts as a client connecting to a cloud-hosted backend. With Aspire 9.1, comes logic to better support GitHub Codespaces including:
[GitHub Codespaces](https://github.com/features/codespaces) offers a cloud-hosted development environment based on Visual Studio Code. It can be accessed directly from a web browser or through Visual Studio Code locally, where Visual Studio Code acts as a client connecting to a cloud-hosted backend. Aspire works well in GitHub Codespaces and includes support for:

- Automatically configure port forwarding with the correct protocol.
- Automatically translate URLs in the Aspire dashboard.

Before Aspire 9.1 it was still possible to use Aspire within a GitHub Codespace, however more manual configuration was required.
- Automatically configuring port forwarding with the correct protocol.
- Automatically translating URLs in the Aspire dashboard.

## GitHub Codespaces vs. Dev Containers

GitHub Codespaces builds upon Visual Studio Code and the [Dev Containers specification](https://containers.dev/implementors/spec/). In addition to supporting GitHub Codespaces, Aspire 9.1 enhances support for using Visual Studio Code and locally hosted Dev Containers. While the experiences are similar, there are some differences. For more information, see [Aspire and Visual Studio Code Dev Containers](/get-started/dev-containers/).
GitHub Codespaces builds upon Visual Studio Code and the [Dev Containers specification](https://containers.dev/implementors/spec/). While the experiences are similar, there are some differences. For more information, see [Aspire and Visual Studio Code Dev Containers](/get-started/dev-containers/).

## Quick start using template repository

To configure GitHub Codespaces for Aspire, use the `.devcontainer/devcontainer.json` file in your repository. The simplest way to get started is by creating a new repository from our [template repository](https://github.com/microsoft/aspire-devcontainer). Consider the following steps:
To configure GitHub Codespaces for Aspire, use the `.devcontainer/devcontainer.json` file in your repository. The simplest way to get started is by creating a new repository from the [Aspire Dev Container template](https://github.com/dotnet/aspire-devcontainer). Consider the following steps:

<Steps>

Expand All @@ -43,7 +41,7 @@ To configure GitHub Codespaces for Aspire, use the `.devcontainer/devcontainer.j

Once you provide the details and select **Create repository**, the repository is created and shown in GitHub.

1. From the new repository, select on the Code button and select the Codespaces tab and then select **Create codespace on main**.
1. From the new repository, select the **Code** button, open the **Codespaces** tab, and then select **Create codespace on main**.

<Image
src={createCodespace}
Expand All @@ -64,12 +62,12 @@ To configure GitHub Codespaces for Aspire, use the `.devcontainer/devcontainer.j
alt="Screenshot showing the terminal prompt ready for use in the codespace."
/>

At this point, the Aspire templates have been installed and the ASP.NET Core developer certificate has been added and accepted.
At this point, the Aspire CLI has been installed and the ASP.NET Core development certificate has been created and trusted inside the Codespace. You can use `aspire new` right away without manually installing `Aspire.ProjectTemplates`.

1. Create a new Aspire project using the starter template.

```bash
dotnet new aspire-starter --name HelloAspire
```bash title="Aspire CLI — Create an Aspire starter app"
aspire new aspire-starter --name HelloAspire
```

This results in many files and folders being created in the repository, which are visible in the **Explorer** panel on the left side of the window.
Expand Down Expand Up @@ -130,14 +128,48 @@ To configure GitHub Codespaces for Aspire, use the `.devcontainer/devcontainer.j

## Manually configuring devcontainer.json

The preceding walkthrough demonstrates the streamlined process of creating a GitHub Codespace using the Aspire Devcontainer template. If you already have an existing repository and wish to utilize Devcontainer functionality with Aspire, add a `devcontainer.json` file to the `.devcontainer` folder within your repository:
The preceding walkthrough demonstrates the streamlined process of creating a GitHub Codespace using the Aspire Dev Container template. If you already have an existing repository and want to use Codespaces with Aspire, add a `devcontainer.json` file to the `.devcontainer` folder within your repository:

<FileTree>
- .devcontainer
- devcontainer.json
</FileTree>

The [template repository](https://github.com/microsoft/aspire-devcontainer) contains a copy of the `devcontainer.json` file that you can use as a starting point, which should be sufficient for Aspire.
The [template repository](https://github.com/dotnet/aspire-devcontainer) contains a copy of the `devcontainer.json` file that you can use as a starting point, which should be sufficient for Aspire.

The following `devcontainer.json` matches the current template repository and works well for most Aspire solutions in Codespaces:

```json title="JSON — .devcontainer/devcontainer.json"
{
"name": "Aspire",
"image": "mcr.microsoft.com/devcontainers/dotnet:dev-10.0-noble",
"features": {
"ghcr.io/devcontainers/features/docker-in-docker:2": {},
"ghcr.io/devcontainers/features/powershell:1": {},
"ghcr.io/devcontainers/features/node:1": {},
"ghcr.io/devcontainers/features/python:1": {},
"ghcr.io/devcontainers-extra/features/uv:1": {}
},
"hostRequirements": {
"cpus": 8,
"memory": "32gb",
"storage": "64gb"
},
"onCreateCommand": "curl -sSL https://aspire.dev/install.sh | bash",
"postStartCommand": "dotnet dev-certs https --trust",
"customizations": {
"vscode": {
"extensions": [
"ms-dotnettools.csdevkit",
"GitHub.copilot-chat",
"GitHub.copilot"
]
}
}
}
```

This configuration installs the Aspire CLI during Codespace creation, so `aspire new` is ready to use as soon as the Codespace finishes building.

## Speed up Codespace creation

Expand Down