Add Python templates and onboarding documentation

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 JavaScript frontend. This template uses a file-based AppHost and includes:
+
+  - **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 with OpenTelemetry instrumentation.
+  - **frontend**: A JavaScript frontend using [React](https://react.dev/) framework with Vite.
+
+  > [!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,21 +107,30 @@ 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, even when using an earlier version of the .NET CLI. To manually specify the .NET version, use 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
+> ```Aspire
+> aspire new aspire-apphost --framework net8.0
 > ```
 
 You need to trust the ASP.NET Core :::no-loc text="localhost"::: certificate before running the app. Run the following command:

docs/get-started/build-aspire-apps-with-python.md

@@ -1,13 +1,16 @@
 ---
 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 AppHost project.
+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 capabilities to it. The sample app in this article demonstrates launching a Python application with Flask. 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)]
 
@@ -194,10 +197,71 @@ 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**: A lightweight WSGI web application framework
+- **FastAPI**: A modern, fast web framework for building APIs with Python
+- **Django**: 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:
+
+- Create an Aspire AppHost project
+- Prepare a Python application with a virtual environment
+- Install the Python hosting package
+- Use the `AddPythonApp` API 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)

docs/get-started/build-aspire-python-app.md

@@ -0,0 +1,192 @@
+---
+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)]
+
+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 and might not be available yet. Once 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:
+
+```Aspire
+aspire new aspire-py-starter
+```
+
+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 `AddPythonScript` to add the Python 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 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)

docs/toc.yml

@@ -53,8 +53,13 @@ items:
       href: get-started/build-aspire-apps-with-nodejs.md
       displayName: node.js,node,express,typescript,javascript,spa,client-side,server-side
     - name: Python apps in Aspire
-      displayName: python,flask,fastapi
-      href: get-started/build-aspire-apps-with-python.md
+      items:
+      - name: Build an Aspire app with Python and JavaScript
+        displayName: python,flask,fastapi,react,javascript,template,new project
+        href: get-started/build-aspire-python-app.md
+      - name: Orchestrate existing Python apps
+        displayName: python,flask,fastapi,onboarding,existing,migrate
+        href: get-started/build-aspire-apps-with-python.md
   - name: AppHost configuration
     href: app-host/configuration.md
   - name: Customize resources