dotnet · Copilot · Oct 17, 2025 · Oct 17, 2025 · Oct 17, 2025 · Oct 21, 2025
diff --git a/docs/fundamentals/aspire-sdk-templates.md b/docs/fundamentals/aspire-sdk-templates.md
@@ -37,6 +37,17 @@ The following Aspire solution templates are available, assume the solution is na
   - **AspireSample.Web**: An [ASP.NET Core Blazor App](/aspnet/core/blazor) project with default Aspire service configurations, this project depends on the [**AspireSample.ServiceDefaults**](#service-defaults) project.
   - **AspireSample.Test**: Either an [MSTest](#mstest-project), [NUnit](#nunit-project), or [xUnit](#xunit-project) test project with project references to the [**AspireSample.AppHost**](#app-host) and an example _WebTests.cs_ file demonstrating an integration test.
 
+<a name="python-app"></a>
+
+- **Aspire Python App**: A full-stack Aspire application with a Python backend and a JavaScript frontend. This template uses a file-based AppHost and includes:
+
+  - **apphost.cs**: A file-based AppHost that orchestrates the Python backend and the JavaScript frontend. It also includes a Redis cache in the solution.
+  - **app**: A Python backend that uses the [FastAPI](https://fastapi.tiangolo.com/) framework with OpenTelemetry instrumentation.
+  - **frontend**: A JavaScript frontend using the [React](https://react.dev/) framework with [Vite](https://vite.dev).
+
+  > [!NOTE]
+  > The Aspire Python template is currently under development. For more information and updates, see [GitHub: Aspire issue #11865](https://github.com/dotnet/aspire/issues/11865). For now, you can manually add Python applications to an existing Aspire solution using the guidance in [Orchestrate Python apps in Aspire](../get-started/build-aspire-apps-with-python.md).
+
 ### Project templates
 
 The following Aspire project templates are available:
@@ -96,18 +107,27 @@ To create an Aspire solution or project using the .NET CLI, use the [dotnet new]
 
 To create a basic [Aspire AppHost](app-host-overview.md) project targeting the latest .NET version:
 
-```dotnetcli
-dotnet new aspire-apphost
+```Aspire
+aspire new aspire-apphost
 ```
 
 To create an Aspire starter app, which is a full solution with a sample UI and backing API included:
 
-```dotnetcli
-dotnet new aspire-starter
+```Aspire
+aspire new aspire-starter
 ```
 
+To create an Aspire app with a Python backend and JavaScript frontend:
+
+```Aspire
+aspire new aspire-py-starter
+```
+
+> [!NOTE]
+> The `aspire-py-starter` template is currently under development. For more information, see [Build an Aspire app with Python and JavaScript](../get-started/build-aspire-python-app.md).
+
 > [!TIP]
-> Aspire templates default to using the latest .NET version, even when using an earlier version of the .NET CLI. To manually specify the .NET version, use the `--framework <tfm>` option, e.g. to create a basic [Aspire AppHost](app-host-overview.md) project targeting .NET 8:
+> Aspire templates default to using the latest .NET version. To manually specify the .NET version, use the .NET CLI with the `--framework <tfm>` option, for example to create a basic [Aspire AppHost](app-host-overview.md) project targeting .NET 8:
 >
 > ```dotnetcli
 > dotnet new aspire-apphost --framework net8.0

diff --git a/docs/get-started/build-aspire-apps-with-python.md b/docs/get-started/build-aspire-apps-with-python.md
@@ -1,16 +1,21 @@
 ---
 title: Orchestrate Python apps in Aspire
-description: Learn how to integrate Python apps into an Aspire AppHost project.
-ms.date: 04/15/2025
+description: Learn how to integrate existing Python apps into an Aspire solution.
+ms.date: 10/17/2025
 ms.custom: sfi-image-nochange
 ---
 
 # Orchestrate Python apps in Aspire
 
-In this article, you learn how to use Python apps in an Aspire AppHost. The sample app in this article demonstrates launching a Python application. The Python extension for Aspire requires the use of virtual environments.
+In this article, you learn how to add existing Python applications to an Aspire solution. This approach is ideal when you have an existing Python codebase and want to add Aspire orchestration and observability to it. The sample app in this article demonstrates launching a Python application with [Flask](https://flask.palletsprojects.com/en/stable/). The Python extension for Aspire requires the use of virtual environments.
+
+> [!TIP]
+> If you're starting a new project from scratch, consider using the Aspire Python template instead. See [Build an Aspire app with Python and JavaScript](build-aspire-python-app.md) for more information.
 
 [!INCLUDE [aspire-prereqs](../includes/aspire-prereqs.md)]
 
+This tutorial also assumes that you have installed the Aspire CLI. For further instructions, see [Install Aspire CLI](../cli/install.md).
+
 Additionally, you need to install [Python](https://www.python.org/downloads) on your machine. The sample app in this article was built with Python version 3.12.4 and pip version 24.1.2. To verify your Python and pip versions, run the following commands:
 
 ```console
@@ -27,8 +32,8 @@ To download Python (including `pip`), see the [Python download page](https://www
 
 To get started launching a Python project in Aspire, use the starter template to first create an Aspire application host:
 
-```dotnetcli
-dotnet new aspire -o PythonSample
+```Aspire
+aspire new aspire -o PythonSample
 ```
 
 In the same terminal session, change directories into the newly created project:
@@ -39,8 +44,8 @@ cd PythonSample
 
 After the template is created, launch the AppHost with the following command to ensure that the AppHost and the [Aspire dashboard](../fundamentals/dashboard/overview.md) run successfully:
 
-```dotnetcli
-dotnet run --project ./PythonSample.AppHost/PythonSample.AppHost.csproj
+```Aspire
+aspire run
 ```
 
 If the Aspire Dashboard doesn't open, open it with the link in the console output. At this point the dashboard won't show any resources. Stop the AppHost by pressing <kbd>Ctrl + C</kbd> in the terminal.
@@ -129,7 +134,7 @@ The preceding code creates a simple Flask app that listens on port 8111 and retu
 Install the Python hosting package by running the following command:
 
 ```dotnetcli
-dotnet add ../PythonSample.AppHost/PythonSample.AppHost.csproj package Aspire.Hosting.Python --version 9.0.0
+dotnet add package Aspire.Hosting.Python --version 9.0.0
 ```
 
 After the package is installed, the project XML should have a new package reference similar to the following example:
@@ -147,8 +152,8 @@ Replace the _AppHost.cs_ code with the following snippet. This code adds the Pyt
 
 Now that you've added the Python hosting package, updated the _AppHost.cs_ file, and created a Python project, you can run the AppHost:
 
-```dotnetcli
-dotnet run --project ../PythonSample.AppHost/PythonSample.AppHost.csproj
+```Aspire
+aspire run
 ```
 
 Launch the dashboard by clicking the link in the console output. The dashboard should display the Python project as a resource.
@@ -194,10 +199,70 @@ Once the AppHost is running, navigate to the dashboard and select the **Structur
 
 :::image source="media/python-telemetry-in-dashboard.png" lightbox="media/python-telemetry-in-dashboard.png" alt-text="Aspire dashboard: Structured logging from Python process.":::
 
+## Onboard existing Python applications
+
+If you have an existing Python application that you want to add to Aspire, here are some key considerations and best practices:
+
+### Common Python frameworks
+
+Aspire works with various Python web frameworks. The most common ones include:
+
+- **[Flask](https://flask.palletsprojects.com/en/stable/)**: A lightweight WSGI web application framework.
+- **[FastAPI](https://fastapi.tiangolo.com/)**: A modern, fast web framework for building APIs with Python.
+- **[Django](https://www.djangoproject.com/)**: A high-level web framework that encourages rapid development.
+
+The integration process is similar across frameworks:
+
+1. Ensure your application can read configuration from environment variables.
+1. Add OpenTelemetry instrumentation for observability.
+1. Use the `AddPythonApp` API in your AppHost to orchestrate the application.
+
+### Migration tips
+
+When migrating an existing Python application to Aspire:
+
+1. **Virtual environments**: Ensure your application uses a virtual environment (`.venv` directory).
+1. **Dependencies**: List all dependencies in a `requirements.txt` file.
+1. **Configuration**: Use environment variables for configuration instead of hardcoded values.
+1. **Port binding**: Make your application read the port from an environment variable (commonly `PORT`).
+1. **Logging**: Configure logging to work with OpenTelemetry for better observability.
+
+### Common pitfalls
+
+Be aware of these common issues when onboarding Python apps:
+
+- **Certificate issues**: When running locally, you might need to set `ASPIRE_ALLOW_UNSECURED_TRANSPORT=true` in your AppHost launch settings.
+- **Path issues**: Ensure the path to your Python entry point file is correct relative to the AppHost project.
+- **Virtual environment activation**: The `AddPythonApp` API handles virtual environment activation automatically—you don't need to activate it manually.
+- **Python version compatibility**: Ensure your Python version is compatible with the packages you're using.
+
+### Multiple Python services
+
+If you have multiple Python services, you can add them all to the same AppHost:
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+var pythonApi = builder.AddPythonApp("python-api", "../python-api", "main.py")
+    .WithHttpEndpoint(port: 8111);
+
+var pythonWorker = builder.AddPythonApp("python-worker", "../python-worker", "worker.py");
+
+builder.Build().Run();
+```
+
 ## Summary
 
-While there are several considerations that are beyond the scope of this article, you learned how to build Aspire solution that integrates with Python. You also learned how to use the `AddPythonApp` API to host Python apps.
+In this article, you learned how to integrate existing Python applications into an Aspire solution. You learned how to:
+
+- Prepare a Python application with a virtual environment.
+- Install the Aspire Python hosting package.
+- Use the `AddPythonApp` API in the AppHost to orchestrate Python apps.
+- Add OpenTelemetry for observability.
+- Handle common pitfalls and best practices for migrating existing Python apps.
 
 ## See also
 
+- [Build an Aspire app with Python and JavaScript](build-aspire-python-app.md)
 - [GitHub: Aspire Samples—Python hosting integration](https://github.com/dotnet/aspire-samples/tree/main/samples/AspireWithPython)
+- [GitHub: Aspire issue #11865 - Python Templates](https://github.com/dotnet/aspire/issues/11865)
diff --git a/docs/get-started/build-aspire-python-app.md b/docs/get-started/build-aspire-python-app.md
@@ -0,0 +1,204 @@
+---
+title: Build an Aspire app with Python and JavaScript
+description: Learn how to create a new Aspire application with a Python backend and JavaScript frontend using the Aspire Python template.
+ms.date: 10/17/2025
+ms.custom: sfi-image-nochange
+ai-usage: ai-assisted
+---
+
+# Build an Aspire app with Python and JavaScript
+
+In this article, you learn how to create a new Aspire application using the Aspire Python template. The template creates a solution with a Python backend (using [FastAPI](https://fastapi.tiangolo.com/)) and a JavaScript frontend (using [React](https://react.dev/)), orchestrated by Aspire. This approach is ideal for Python developers who want to build observable, production-ready applications with modern JavaScript frontends.
+
+> [!NOTE]
+> The Aspire Python template is currently under development. This documentation will be updated as the template becomes available. For now, you can follow the guidance in [Orchestrate Python apps in Aspire](build-aspire-apps-with-python.md) to manually add Python applications to an existing Aspire solution.
+
+> [!TIP]
+> If you already have an existing Python application and want to add Aspire to it, see [Orchestrate Python apps in Aspire](build-aspire-apps-with-python.md).
+
+[!INCLUDE [aspire-prereqs](../includes/aspire-prereqs.md)]
+
+This tutorial also assumes that you have installed the Aspire CLI. For further instructions, see [Install Aspire CLI](../cli/install.md).
+
+Additionally, you need to install [Python](https://www.python.org/downloads) on your machine. This article requires Python version 3.12 or later. To verify your Python and pip versions, run the following commands:
+
+```console
+python --version
+```
+
+```console
+pip --version
+```
+
+To download Python (including `pip`), see the [Python download page](https://www.python.org/downloads).
+
+You also need to install [Node.js](https://nodejs.org/en/download/package-manager) for the JavaScript frontend. To verify your Node.js and npm versions, run the following commands:
+
+```console
+node --version
+```
+
+```console
+npm --version
+```
+
+To download Node.js (including `npm`), see the [Node.js download page](https://nodejs.org/en/download/package-manager).
+
+## Create an Aspire project using the Python template
+
+> [!IMPORTANT]
+> The `aspire-py-starter` template is currently being developed. Once it's released, you'll be able to create a Python-based Aspire application using the following command. For updates on template availability, see [Aspire Python Templates (issue #11865)](https://github.com/dotnet/aspire/issues/11865).
+
+To create a new Aspire application with a Python backend and JavaScript frontend, use the `aspire-py-starter` template:
+
+1. Execute the following command
+
+    ```Aspire
+    aspire new aspire-py-starter
+    ```
+
+1. For the project name, type **MyPythonApp**, and then press <kbd>Enter</kbd>.
+1. To accept the default output path, press <kbd>Enter</kbd>.
+1. To select the default template version, press <kbd>Enter</kbd>.
+1. When asked whether to use a Redis cache, select **No** and then press <kbd>Enter</kbd>.
+1. When asked whether to create a test project, select **No** and then press <kbd>Enter</kbd>.
+
+The Aspire CLI creates the new solution.
+
+This command creates a new Aspire solution with the following structure:
+
+- **apphost.cs**: A file-based AppHost that orchestrates the Python backend and JavaScript frontend.
+- **app**: A Python backend using [FastAPI](https://fastapi.tiangolo.com/) framework.
+- **frontend**: A JavaScript frontend using [React](https://react.dev/) framework with Vite.
+
+## Explore the project structure
+
+Navigate to the newly created project directory:
+
+```console
+cd MyPythonApp
+```
+
+### File-based AppHost
+
+The solution uses a file-based AppHost with a single _apphost.cs_ file. This file contains the orchestration logic for both the Python backend and JavaScript frontend. The AppHost uses `AddUvicornApp` to add the backend and `AddViteApp` to add the React frontend.
+
+### Python backend
+
+The Python backend is located in the _app_ directory. It uses the [FastAPI](https://fastapi.tiangolo.com/) framework to create RESTful APIs. The backend includes:
+
+- A virtual environment for Python dependencies.
+- A _requirements.txt_ file listing required Python packages.
+- An _app.py_ file containing the FastAPI application code.
+- OpenTelemetry instrumentation for observability.
+
+### JavaScript frontend
+
+The JavaScript frontend is located in the _frontend_ directory. It uses [React](https://react.dev/) with [Vite](https://vite.dev/) to create the user interface. The frontend includes:
+
+- A _package.json_ file listing required npm packages.
+- Source code in the _src_ directory.
+- Configuration for connecting to the backend API.
+
+## Set up the Python environment
+
+Navigate to the Python backend directory:
+
+```console
+cd app
+```
+
+Create and activate a Python virtual environment:
+
+### [Unix/macOS](#tab/bash)
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+```
+
+### [Windows](#tab/powershell)
+
+```powershell
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+```
+
+---
+
+Install the Python dependencies:
+
+```console
+python -m pip install --upgrade pip
+python -m pip install -r requirements.txt
+```
+
+## Set up the JavaScript environment
+
+Navigate to the JavaScript frontend directory:
+
+```console
+cd ../frontend
+```
+
+Install the npm dependencies:
+
+```console
+npm install
+```
+
+## Run the application
+
+Navigate back to the solution root directory:
+
+```console
+cd ..
+```
+
+Run the AppHost to start the application:
+
+```Aspire
+aspire run
+```
+
+The Aspire dashboard opens in your browser. You should see both the Python backend and JavaScript frontend listed as resources.
+
+## Explore the Aspire dashboard
+
+The Aspire dashboard provides a unified view of your application's resources, including:
+
+- **Resources**: View all running services (Python backend and JavaScript frontend).
+- **Logs**: See consolidated logs from all services.
+- **Traces**: Monitor distributed traces across your application.
+- **Metrics**: View performance metrics and telemetry data.
+
+Select the **Endpoints** link for each resource to access:
+
+- The React frontend user interface.
+- The FastAPI backend API documentation (Swagger UI).
+
+## Understand telemetry and observability
+
+The Python backend and JavaScript frontend are both configured with OpenTelemetry for observability. This means:
+
+- **Logs** from both applications are collected and displayed in the Aspire dashboard.
+- **Traces** show the flow of requests across services.
+- **Metrics** provide insights into application performance.
+
+The template includes OpenTelemetry packages configured to export telemetry data to the Aspire dashboard automatically.
+
+## Next steps
+
+Now that you have a working Aspire application with Python and JavaScript:
+
+- Explore the FastAPI backend code and add new API endpoints.
+- Customize the React frontend to create your user interface.
+- Add additional services or resources to your AppHost.
+- Deploy your application to a cloud environment.
+
+## See also
+
+- [Orchestrate Python apps in Aspire](build-aspire-apps-with-python.md)
+- [Orchestrate Node.js apps in Aspire](build-aspire-apps-with-nodejs.md)
+- [Aspire templates](../fundamentals/aspire-sdk-templates.md)
+- [GitHub: Aspire issue #11865 - Python Templates](https://github.com/dotnet/aspire/issues/11865)