diff --git a/src/frontend/src/assets/get-started/aspire-dashboard-in-devcontainer.png b/src/frontend/src/assets/get-started/aspire-dashboard-in-devcontainer.png deleted file mode 100644 index 09f7600a4..000000000 Binary files a/src/frontend/src/assets/get-started/aspire-dashboard-in-devcontainer.png and /dev/null differ diff --git a/src/frontend/src/assets/get-started/codespace-launch-apphost.png b/src/frontend/src/assets/get-started/codespace-launch-apphost.png deleted file mode 100644 index 57b0496ad..000000000 Binary files a/src/frontend/src/assets/get-started/codespace-launch-apphost.png and /dev/null differ diff --git a/src/frontend/src/assets/get-started/codespaces-debug-console.png b/src/frontend/src/assets/get-started/codespaces-debug-console.png deleted file mode 100644 index 94672ab20..000000000 Binary files a/src/frontend/src/assets/get-started/codespaces-debug-console.png and /dev/null differ diff --git a/src/frontend/src/assets/get-started/codespaces-explorer-panel.png b/src/frontend/src/assets/get-started/codespaces-explorer-panel.png deleted file mode 100644 index c283cc92f..000000000 Binary files a/src/frontend/src/assets/get-started/codespaces-explorer-panel.png and /dev/null differ diff --git a/src/frontend/src/assets/get-started/codespaces-translated-urls.png b/src/frontend/src/assets/get-started/codespaces-translated-urls.png deleted file mode 100644 index d260045c2..000000000 Binary files a/src/frontend/src/assets/get-started/codespaces-translated-urls.png and /dev/null differ diff --git a/src/frontend/src/assets/get-started/devcontainer-build-completed.png b/src/frontend/src/assets/get-started/devcontainer-build-completed.png deleted file mode 100644 index 82333fc0a..000000000 Binary files a/src/frontend/src/assets/get-started/devcontainer-build-completed.png and /dev/null differ diff --git a/src/frontend/src/assets/get-started/new-repository-from-template-dark.png b/src/frontend/src/assets/get-started/new-repository-from-template-dark.png index ef6f2ed16..142639929 100644 Binary files a/src/frontend/src/assets/get-started/new-repository-from-template-dark.png and b/src/frontend/src/assets/get-started/new-repository-from-template-dark.png differ diff --git a/src/frontend/src/assets/get-started/new-repository-from-template-light.png b/src/frontend/src/assets/get-started/new-repository-from-template-light.png index 01b4b95ea..436b1c8eb 100644 Binary files a/src/frontend/src/assets/get-started/new-repository-from-template-light.png and b/src/frontend/src/assets/get-started/new-repository-from-template-light.png differ diff --git a/src/frontend/src/assets/get-started/vscode-run-button.png b/src/frontend/src/assets/get-started/vscode-run-button.png deleted file mode 100644 index 542365aa0..000000000 Binary files a/src/frontend/src/assets/get-started/vscode-run-button.png and /dev/null differ diff --git a/src/frontend/src/content/docs/get-started/dev-containers.mdx b/src/frontend/src/content/docs/get-started/dev-containers.mdx index c9bc28426..a7cecc55b 100644 --- a/src/frontend/src/content/docs/get-started/dev-containers.mdx +++ b/src/frontend/src/content/docs/get-started/dev-containers.mdx @@ -1,23 +1,23 @@ --- title: Dev Containers in Visual Studio Code -seoTitle: Aspire dev containers for Visual Studio Code overview -description: Use Aspire with Dev Containers in Visual Studio Code to get reproducible, containerized development environments with the Aspire CLI, dashboard, and tooling preinstalled. +seoTitle: Build polyglot Aspire apps in VS Code Dev Containers +description: Use Aspire with Visual Studio Code Dev Containers to build and run multi-language apps in a reproducible environment with the CLI and dashboard ready. --- import { Image } from 'astro:assets'; import { Steps } from '@astrojs/starlight/components'; import FileTree from 'starlight-plugin-icons/components/FileTree.astro'; -import { Kbd } from 'starlight-kbd/components'; import ThemeImage from '@components/ThemeImage.astro'; import newRepoFromTemplateDark from '@assets/get-started/new-repository-from-template-dark.png'; import newRepoFromTemplateLight from '@assets/get-started/new-repository-from-template-light.png'; import reopenInContainer from '@assets/get-started/reopen-in-container.png'; -import devcontainerBuildCompleted from '@assets/get-started/devcontainer-build-completed.png'; -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 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. +The [Dev Containers Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) lets your team define SDKs, command-line tools, editor extensions, and supporting services as part of a repository. + +The maintained Aspire template starts from Ubuntu and installs Aspire, Docker-in-Docker, Node.js, Python and uv, .NET, and PowerShell as peer [Dev Container Features](https://containers.dev/features). The template is intentionally broad, so you can remove or replace any runtime your app doesn't need. Aspire can run a TypeScript AppHost and orchestrate app resources without a separately installed .NET SDK. + +Aspire also configures forwarded ports so the dashboard and resource endpoints are easier to open from Visual Studio Code. ## Dev Containers vs. GitHub Codespaces @@ -25,70 +25,63 @@ Using Dev Containers in Visual Studio Code is similar to using 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 the [Aspire Dev Container template](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/microsoft/aspire-devcontainer). Follow these steps: 1. [Create a new repository](https://github.com/new?template_name=aspire-devcontainer&template_owner=microsoft) using our template. - + - Once you provide the details and select **Create repository**, the repository is created and shown in GitHub. + Once you provide the details and select **Create repository**, the repository is created and shown in GitHub. 1. Clone the repository to your local developer workstation using the following command: - ```bash - git clone https://github.com/// + ```bash title="Clone the repository" + git clone https://github.com//.git + cd ``` -1. Open the repository in Visual Studio Code. After a few moments Visual Studio Code detects the `.devcontainer/devcontainer.json` file and prompts to open the repository inside a container. Select whichever option is most appropriate for your workflow. +1. Open the repository in Visual Studio Code. After a few moments, Visual Studio Code detects the `.devcontainer/devcontainer.json` file and prompts to open the repository inside a container. Select whichever option is most appropriate for your workflow. Screenshot showing VS Code prompt to open the repository inside a container. - 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`. + After a few moments, the files become visible and the Dev Container finishes setting up. The template installs the Aspire CLI and several language runtimes, but it doesn't choose an application language or restore app-specific dependencies for you. - Screenshot showing the dev container build completed notification in VS Code. - -1. Open a new terminal window in Visual Studio Code () and create a new Aspire project using the Aspire CLI. +1. Open a terminal in Visual Studio Code and start the interactive project creator: - ```bash title="Aspire CLI — Create an Aspire starter app" - aspire new aspire-starter --name HelloAspire - ``` + ```bash title="Choose an Aspire starter" + aspire new + ``` - After a few moments, the project will be created and initial dependencies restored. + Choose the TypeScript, Python, C#, or mixed-language starter that fits your app, then provide a name when prompted. For this walkthrough, use `aspire-app` as the output directory. -1. Open the `HelloAspire.AppHost/AppHost.cs` file in the editor and select the run button on the top right corner of the editor window. This run button is provided by the [Aspire VS Code extension](/get-started/aspire-vscode-extension/) or [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit). +1. Change to the generated app directory and start dev-time orchestration: - Screenshot showing the run button in the VS Code editor toolbar. + ```bash title="Run the Aspire app" + cd ./aspire-app + aspire run + ``` - Visual Studio Code builds and starts the Aspire AppHost and automatically opens the Aspire Dashboard. Because the endpoints hosted in the container are using a self-signed certificate the first time, you access an endpoint for a specific Dev Container you're presented with a certificate error. + The Aspire CLI finds the AppHost, starts its resources, and prints a dashboard URL. Open that URL from the terminal to inspect your running app. - Screenshot showing the browser certificate error when accessing the dashboard. + Visual Studio Code forwards the dashboard and resource ports from processes and nested containers. Links in the dashboard open the corresponding forwarded endpoints on your host. - The certificate error is expected. Once you've confirmed that the URL being requested corresponds to the dashboard in the Dev Container you can ignore this warning. + The template runs `aspire certs trust --non-interactive` when the container starts and adds the .NET development certificate trust directory (`~/.aspnet/dev-certs/trust`) to `SSL_CERT_DIR` for OpenSSL-based tools inside the container. Your host browser has a separate trust store, so it might display a certificate warning the first time you open a forwarded HTTPS endpoint. Screenshot of the Aspire dashboard running successfully in 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. + Confirm that the URL belongs to the local forwarded endpoint before you continue past the warning. 1. Commit changes to the GitHub repository. @@ -96,232 +89,90 @@ To configure Dev Containers in Visual Studio Code, use the `.devcontainer/devcon -## Manually configuring devcontainer.json +## Use Aspire in an existing Dev Container -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: +If your repository already exists, add a `devcontainer.json` file to its `.devcontainer` folder: + - .devcontainer - devcontainer.json + -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. +Use the maintained [Aspire template configuration](https://github.com/microsoft/aspire-devcontainer/blob/main/.devcontainer/devcontainer.json) as your starting point. Linking to the source file keeps your setup aligned with the tested template as its feature versions and lifecycle settings change. + +The template keeps Aspire and each language runtime separate: + +| Tooling | Purpose | +| -------------------------------- | ---------------------------------------------------------------------- | +| Aspire CLI and VS Code extension | Create, run, debug, and observe distributed apps | +| Docker-in-Docker | Run container resources such as databases, caches, and message brokers | +| Node.js LTS | Develop JavaScript and TypeScript apps | +| Python and uv | Develop Python apps and manage packages and virtual environments | +| .NET SDK and C# Dev Kit | Develop .NET apps | +| PowerShell | Run cross-platform automation | + +Remove language features and matching editor extensions that your repository doesn't need, or change their versions to match your app. The [Aspire Dev Container Feature](https://github.com/microsoft/aspire-devcontainer-feature) installs the Aspire CLI and shared editor and port-forwarding settings; language SDKs remain a choice made by the consuming configuration. :::note -Install the Aspire CLI during container creation so `aspire new` is ready to use as soon as the container finishes building. +The template doesn't run an application-specific restore command. Restore dependencies with the package manager your app uses, such as `npm install`, `uv sync`, or `dotnet restore`. ::: -## Dev Container scenarios +## Customize the environment -The basic Aspire Dev Container template works well for simple scenarios, but you might need additional configuration depending on your specific requirements. The following sections provide examples for various common scenarios. +### Choose language tooling -### Stateless .NET apps only +Treat the template as a polyglot preset rather than a required tool list. Keep only the runtimes, package managers, and editor extensions used by your repository. You can also add Dev Container Features for Java, Go, Rust, or other ecosystems that your Aspire app orchestrates. -For simple Aspire projects that only use .NET project resources without external containers or complex orchestration, you can use a minimal Dev Container configuration: +Aspire's orchestration model doesn't require every resource to use the same language as the AppHost. A TypeScript AppHost can coordinate Python, JavaScript, .NET, executable, and container resources in one app. -```json title=".devcontainer/devcontainer.json" -{ - "name": "Aspire - Simple", - "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": { - "extensions": ["ms-dotnettools.csdevkit"] - } - } -} -``` +### Run container resources -This minimal configuration is suitable for Aspire apps that orchestrate only .NET services without external dependencies. - -### Adding Node.js resources - -If your Aspire app includes Node.js resources, add the Node.js feature to your Dev Container: - -```json title=".devcontainer/devcontainer.json" -{ - "name": "Aspire with Node.js", - "image": "mcr.microsoft.com/devcontainers/dotnet:dev-10.0-noble", - "features": { - "ghcr.io/devcontainers/features/node:1": { - "version": "lts" - } - }, - "onCreateCommand": "curl -sSL https://aspire.dev/install.sh | bash", - "postStartCommand": "dotnet dev-certs https --trust", - "customizations": { - "vscode": { - "extensions": [ - "ms-dotnettools.csdevkit", - "ms-vscode.vscode-typescript-next" - ] - } - } -} -``` +Keep Docker-in-Docker when your AppHost starts container resources. It gives Aspire an isolated Docker daemon inside the Dev Container, which avoids depending on host-specific socket mounting but requires additional CPU, memory, storage, and privileges. -This configuration provides both .NET and Node.js development capabilities within the same container environment. - -### Container orchestration with Docker-in-Docker - -When your Aspire app orchestrates container resources, you need Docker-in-Docker (DinD) support. Here's a basic configuration: - -```json title=".devcontainer/devcontainer.json" -{ - "name": "Aspire with Containers", - "image": "mcr.microsoft.com/devcontainers/dotnet:dev-10.0-noble", - "features": { - "ghcr.io/devcontainers/features/docker-in-docker:2": { - "version": "latest", - "enableNonRootDocker": true, - "moby": true - } - }, - "hostRequirements": { - "cpus": 4, - "memory": "16gb", - "storage": "32gb" - }, - "onCreateCommand": "curl -sSL https://aspire.dev/install.sh | bash", - "postStartCommand": "dotnet dev-certs https --trust", - "customizations": { - "vscode": { - "extensions": ["ms-dotnettools.csdevkit", "ms-azuretools.vscode-docker"] - } - } -} -``` +The maintained template requests 8 CPUs, 32 GB of memory, and 64 GB of storage because it includes several language toolchains and supports nested containers. Reduce those values only after testing the resources your app starts. -#### Advanced container networking - -If you encounter networking issues between containers or need IPv6 support, you can add additional network configuration: - -```json title=".devcontainer/devcontainer.json" -{ - "name": "Aspire with Advanced Networking", - "image": "mcr.microsoft.com/devcontainers/dotnet:dev-10.0-noble", - "features": { - "ghcr.io/devcontainers/features/docker-in-docker:2": { - "version": "latest", - "enableNonRootDocker": true, - "moby": true - } - }, - "runArgs": [ - "--sysctl", - "net.ipv6.conf.all.disable_ipv6=0", - "--sysctl", - "net.ipv6.conf.default.forwarding=1", - "--sysctl", - "net.ipv6.conf.all.forwarding=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", "ms-azuretools.vscode-docker"] - } - } -} -``` +For advanced networking or IPv6 requirements, add the necessary `runArgs` to your copy of the template and verify them with the container runtime used by your team. -:::caution[Docker-in-Docker considerations] - -- Docker-in-Docker requires higher resource allocation including increased CPU, memory, and storage. -- The advanced networking configuration above includes IPv6 forwarding settings that may be needed for complex container-to-container communication scenarios. -- This configuration works with Docker Desktop but may have limitations with Rancher Desktop. -- Network connectivity between containers might require additional configuration depending on your specific use case. - ::: - -### Dapr integration examples - -For Aspire apps that integrate with Dapr, you can set up Dapr components in your Dev Container. For more information, see [Aspire Dapr integration](/integrations/frameworks/dapr/dapr-get-started/). - -#### Basic Dapr setup - -```json title=".devcontainer/devcontainer.json" -{ - "name": "Aspire with Dapr", - "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": "curl -sSL https://aspire.dev/install.sh | bash", - "postCreateCommand": "dotnet dev-certs https --trust && dapr init", - "customizations": { - "vscode": { - "extensions": ["ms-dotnettools.csdevkit", "ms-azuretools.vscode-dapr"] - } - } -} -``` +### Configure HTTPS certificates + +The template trusts Aspire's development certificate every time the container starts: -#### Dapr with external backends - -For more complex Dapr scenarios that use external backends (Redis, PostgreSQL), you can use Docker Compose: - -```json title=".devcontainer/devcontainer.json" -{ - "name": "Aspire with Dapr and Backends", - "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": "curl -sSL https://aspire.dev/install.sh | bash", - "postCreateCommand": [ - "dotnet dev-certs https --trust", - "docker compose up -d", - "dapr init" - ], - "customizations": { - "vscode": { - "extensions": [ - "ms-dotnettools.csdevkit", - "ms-azuretools.vscode-dapr", - "ms-azuretools.vscode-docker" - ] - } - } -} +```bash title="Trust Aspire development certificates" +aspire certs trust --non-interactive ``` +It also adds the .NET development certificate trust directory (`~/.aspnet/dev-certs/trust`) to `SSL_CERT_DIR`, so OpenSSL-based tools such as `curl` can verify HTTPS endpoints inside the container. This trust doesn't automatically extend to browsers or tools running on the host. + +### Add scenario-specific tools + +Add only the tools required by your workflow. For example, a Dapr-based app can add the Dapr CLI feature and initialize Dapr during container creation. For Aspire-specific setup, see [Aspire Dapr integration](/integrations/frameworks/dapr/dapr-get-started/). + ## Common considerations When using Dev Containers with Aspire, keep the following considerations in mind: **Resource requirements** -- **Basic .NET apps**: Standard Dev Container resources are sufficient for simple scenarios. -- **Container orchestration**: A minimum of 8 CPUs, 32GB memory, and 64GB storage is recommended. -- **Complex scenarios with Dapr/Kubernetes**: Higher resource allocation is recommended for optimal performance. +- Apps that run only host processes need fewer resources than apps that start nested containers. +- Multi-language repositories need enough storage for every selected runtime and package cache. +- Dapr, Kubernetes, and larger container topologies might require more resources than the template defaults. **Networking** -- IPv6 configuration may be required for container-to-container communication. -- Port forwarding is automatically handled by Aspire. -- External service connectivity depends on your container runtime configuration. +- Aspire and Visual Studio Code automatically forward dashboard and resource ports. +- Nested container networking depends on the Docker-in-Docker configuration. +- IPv6 and external service access might require additional container runtime settings. **Performance** -- Docker-in-Docker scenarios incur performance overhead compared to native Docker. -- Consider using Docker outside of Docker (DooD) for production workflows. -- Local development and deployment scenarios may require different configurations. +- Docker-in-Docker adds startup and I/O overhead. +- Codespaces prebuilds can reduce environment creation time for cloud-hosted development. +- Remove unused runtimes and extensions to reduce image size and rebuild time. **Security** - Dev Containers run with elevated privileges when using Docker-in-Docker. -- 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. +- Certificate trust inside the container doesn't automatically trust the same endpoint on the host. - Consider security implications when exposing ports in cloud environments. diff --git a/src/frontend/src/content/docs/get-started/github-codespaces.mdx b/src/frontend/src/content/docs/get-started/github-codespaces.mdx index 4d29ab67b..d398a0f30 100644 --- a/src/frontend/src/content/docs/get-started/github-codespaces.mdx +++ b/src/frontend/src/content/docs/get-started/github-codespaces.mdx @@ -1,6 +1,6 @@ --- title: Use Aspire with GitHub Codespaces -description: Use Aspire with GitHub Codespaces for cloud-based development — preconfigured containers, port forwarding, dashboard access, and a ready-to-go Aspire CLI experience. +description: Use Aspire in GitHub Codespaces to build multi-language apps with a preconfigured Dev Container, automatic port forwarding, and dashboard links. --- import { Image } from 'astro:assets'; @@ -12,15 +12,14 @@ import newRepoFromTemplateLight from '@assets/get-started/new-repository-from-te import createCodespace from '@assets/get-started/create-codespace-from-repository.png'; import buildingCodespace from '@assets/get-started/building-codespace-image.png'; import codespaceTerminal from '@assets/get-started/codespace-terminal.png'; -import codespacesExplorer from '@assets/get-started/codespaces-explorer-panel.png'; -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. Aspire works well in GitHub Codespaces and includes support for: +[GitHub Codespaces](https://github.com/features/codespaces) provides a cloud-hosted development environment based on Visual Studio Code and the Dev Containers specification. You can use it from a browser or connect from Visual Studio Code on your local machine. -- Automatically configuring port forwarding with the correct protocol. -- Automatically translating URLs in the Aspire dashboard. +The maintained Aspire template provides a polyglot environment with Aspire, Docker-in-Docker, Node.js, Python and uv, .NET, and PowerShell installed as peer tooling. Aspire support in Codespaces also includes: + +- Automatic port forwarding with the correct protocol. +- Dashboard links translated to Codespaces URLs. +- GitHub identity protection for forwarded endpoints. ## GitHub Codespaces vs. Dev Containers @@ -28,150 +27,113 @@ GitHub Codespaces builds upon Visual Studio Code and the [Dev Containers specifi ## 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 the [Aspire Dev Container template](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/microsoft/aspire-devcontainer). Follow these steps: 1. [Create a new repository](https://github.com/new?template_name=aspire-devcontainer&template_owner=microsoft) using our template. - + - Once you provide the details and select **Create repository**, the repository is created and shown in GitHub. + Once you provide the details and select **Create repository**, the repository is created and shown in GitHub. 1. From the new repository, select the **Code** button, open the **Codespaces** tab, and then select **Create codespace on main**. - Screenshot showing how to create a new codespace from the repository on GitHub. - - After you select **Create codespace on main**, you navigate to a web-based version of Visual Studio Code. Before you use the Codespace, the containerized development environment needs to be prepared. This process happens automatically on the server and you can review progress by selecting the **Building codespace** link on the notification in the bottom right of the browser window. - - Screenshot showing the building codespace notification in VS Code. + Screenshot showing how to create a new codespace from the repository on GitHub. - When the container image has finished being built the **Terminal** prompt appears which signals that the environment is ready to be interacted with. + After you select **Create codespace on main**, you navigate to a web-based version of Visual Studio Code. Before you use the Codespace, the containerized development environment needs to be prepared. This process happens automatically on the server and you can review progress by selecting the **Building codespace** link on the notification in the bottom right of the browser window. - Screenshot showing the terminal prompt ready for use in the codespace. + Screenshot showing the building codespace notification in VS Code. - At this point, the Aspire CLI has been installed and the local HTTPS development certificate for .NET apps has been created and trusted inside the Codespace. You can use `aspire new` right away without manually installing `Aspire.ProjectTemplates`. + When the container image finishes building, the **Terminal** prompt appears to indicate that the environment is ready. -1. Create a new Aspire project using the starter template. + Screenshot showing the terminal prompt ready for use in the codespace. - ```bash title="Aspire CLI — Create an Aspire starter app" - aspire new aspire-starter --name HelloAspire - ``` + At this point, the Aspire CLI and the template's language tooling are ready. The template doesn't choose an application language or restore app-specific dependencies for you. - 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. +1. Start the interactive project creator: - Screenshot of the VS Code Explorer panel showing the newly created Aspire project structure. + ```bash title="Choose an Aspire starter" + aspire new + ``` -1. Launch the AppHost via the `HelloAspire.AppHost/AppHost.cs` file, by selecting the **Run project** button near the top-right corner of the **Tab bar**. + Choose the TypeScript, Python, C#, or mixed-language starter that fits your app, then provide a name when prompted. For this walkthrough, use `aspire-app` as the output directory. - Screenshot showing how to launch the AppHost using the Run project button in VS Code. +1. Change to the generated app directory and start dev-time orchestration: - After a few moments the **Debug Console** panel is displayed, and it includes a link to the Aspire dashboard exposed on a GitHub Codespaces endpoint with the authentication token. + ```bash title="Run the Aspire app" + cd ./aspire-app + aspire run + ``` - Screenshot of the Debug Console showing the Aspire dashboard URL with authentication token. +1. Open the dashboard by selecting the URL printed by `aspire run`. Codespaces opens the forwarded dashboard in a separate browser tab. -1. Open the Aspire dashboard by selecting the dashboard URL in the **Debug Console**. This opens the Aspire dashboard in a separate tab within your browser. + The dashboard translates resource endpoints from their container-local addresses to unique subdomains on the `app.github.dev` domain. - You notice on the dashboard that all HTTP/HTTPS endpoints defined on resources have had their typical `localhost` address translated to a unique fully qualified subdomain on the `app.github.dev` domain. + Traffic to each of these endpoints is automatically forwarded to the underlying process or container running within the Codespace. This includes development time tools such as PgAdmin and Redis Insight. - Screenshot of the Aspire dashboard showing translated URLs using GitHub Codespaces domains. - - Traffic to each of these endpoints is automatically forwarded to the underlying process or container running within the Codespace. This includes development time tools such as PgAdmin and Redis Insight. - - :::note - In addition to the authentication token embedded within the URL of the dashboard link of the **Debug Console**, endpoints also require authentication via your GitHub identity to avoid port forwarded endpoints being accessible to everyone. For more information on port forwarding in GitHub Codespaces, see [Forwarding ports in your codespace](https://docs.github.com/codespaces/developing-in-a-codespace/forwarding-ports-in-your-codespace?tool=webui). - ::: + :::note + The dashboard URL includes its Aspire authentication token. Codespaces also requires your GitHub identity for private forwarded ports so those endpoints aren't accessible to everyone. For more information, see [Forwarding ports in your codespace](https://docs.github.com/codespaces/developing-in-a-codespace/forwarding-ports-in-your-codespace?tool=webui). + ::: 1. Commit changes to the GitHub repository. - GitHub Codespaces doesn't automatically commit your changes to the branch you're working on in GitHub. You have to use the **Source Control** panel to stage and commit the changes and push them back to the repository. + GitHub Codespaces doesn't automatically commit your changes to the branch you're working on in GitHub. You have to use the **Source Control** panel to stage and commit the changes and push them back to the repository. - Working in a GitHub Codespace is similar to working with Visual Studio Code on your own machine. You can checkout different branches and push changes just like you normally would. In addition, you can easily spin up multiple Codespaces simultaneously if you want to quickly work on another branch without disrupting your existing debug session. For more information, see [Developing in a codespace](https://docs.github.com/codespaces/developing-in-a-codespace/developing-in-a-codespace?tool=webui). + Working in a GitHub Codespace is similar to working with Visual Studio Code on your own machine. You can check out different branches and push changes just like you normally would. You can also create multiple Codespaces when you want to work on another branch without disrupting a running app. For more information, see [Developing in a codespace](https://docs.github.com/codespaces/developing-in-a-codespace/developing-in-a-codespace?tool=webui). 1. Clean up your Codespace. - GitHub Codespaces are temporary development environments and while you might use one for an extended period of time, they should be considered a disposable resource that you recreate as needed (with all of the customization/setup contained within the `devcontainer.json` and associated configuration files). + Treat GitHub Codespaces as disposable development environments that you can recreate as needed. Keep environment setup in `devcontainer.json` and related configuration files, and commit your source changes before deleting a Codespace. - To delete your GitHub Codespace, visit the GitHub Codespaces page. This shows you a list of all of your Codespaces. From here you can perform management operations on each Codespace, including deleting them. + To delete a Codespace, visit the [GitHub Codespaces page](https://github.com/codespaces) and open its management menu. - GitHub charges for the use of Codespaces. For more information, see [Managing the cost of GitHub Codespaces in your organization](https://docs.github.com/codespaces/managing-codespaces-for-your-organization/choosing-who-owns-and-pays-for-codespaces-in-your-organization). + GitHub charges for the use of Codespaces. For more information, see [Managing the cost of GitHub Codespaces in your organization](https://docs.github.com/codespaces/managing-codespaces-for-your-organization/choosing-who-owns-and-pays-for-codespaces-in-your-organization). - :::note - Aspire supports the use of Dev Containers in Visual Studio Code independent of GitHub Codespaces. For more information on how to use Dev Containers locally, see [Aspire and Dev Containers in Visual Studio Code](/get-started/dev-containers/). - ::: + :::note + Aspire supports the use of Dev Containers in Visual Studio Code independent of GitHub Codespaces. For more information on how to use Dev Containers locally, see [Aspire and Dev Containers in Visual Studio Code](/get-started/dev-containers/). + ::: -## Manually configuring devcontainer.json +## Use Aspire in an existing Codespaces 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: +If your repository already exists, add a `devcontainer.json` file to its `.devcontainer` folder: + - .devcontainer - devcontainer.json + -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 following `devcontainer.json` matches the current template repository and works well for most Aspire solutions in Codespaces: - -```json title=".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. +Use the maintained [Aspire template configuration](https://github.com/microsoft/aspire-devcontainer/blob/main/.devcontainer/devcontainer.json) as your starting point. Linking to the source file keeps your Codespace aligned with the tested feature versions, lifecycle commands, and host requirements as they change. + +The template starts from Ubuntu and layers Aspire, Docker-in-Docker, Node.js, Python and uv, .NET, and PowerShell as independent Dev Container Features. Keep the runtimes and editor extensions your repository needs and remove the rest. Aspire can run a TypeScript AppHost and orchestrate app resources without a separately installed .NET SDK. + +The template requests 8 CPUs, 32 GB of memory, and 64 GB of storage because it supports several language toolchains and nested containers. Adjust those requirements for your app and Codespaces budget. + +:::note +The template doesn't run an application-specific restore command. Restore dependencies with the package manager your app uses, such as `npm install`, `uv sync`, or `dotnet restore`. +::: + +The template runs `aspire certs trust --non-interactive` whenever the Codespace starts and adds the .NET development certificate trust directory (`~/.aspnet/dev-certs/trust`) to `SSL_CERT_DIR`. This lets OpenSSL-based tools inside the Codespace verify Aspire HTTPS endpoints without making certificate setup language-specific. ## Speed up Codespace creation -Creating a GitHub Codespace can take some time as it prepares the underlying container image. To expedite this process, you can utilize _prebuilds_ to significantly reduce the creation time to approximately 30-60 seconds (exact timing might vary). For more information on GitHub Codespaces prebuilds, see [GitHub Codespaces prebuilds](https://docs.github.com/codespaces/prebuilding-your-codespaces/about-github-codespaces-prebuilds). +Creating a Codespace can take time while GitHub builds the Dev Container and installs its features. Configure _prebuilds_ to prepare that environment before a developer opens it. Startup lifecycle commands, including Aspire certificate trust, still run when a prebuilt Codespace starts or resumes. + +For more information, see [GitHub Codespaces prebuilds](https://docs.github.com/codespaces/prebuilding-your-codespaces/about-github-codespaces-prebuilds).