Add WSL-specific Podman documentation and troubleshooting guide

docs/fundamentals/setup-tooling.md

@@ -133,6 +133,41 @@ For more information, see [Install Podman on Windows](https://podman.io/docs/ins
 
 ---
 
+### WSL (Windows Subsystem for Linux) considerations
+
+When using Podman with WSL, ensure that the `podman` executable is available in your `PATH` and not just defined as a shell alias. .NET Aspire resolves container runtimes by searching for the executable in the system PATH, and shell aliases aren't recognized during this process.
+
+**Common issues and solutions:**
+
+- **Podman installed in a separate WSL distribution**: If Podman is installed in a different WSL distribution than your .NET Aspire application, the `podman` command might not be available in your current distribution's PATH.
+
+  **Solution**: Install Podman directly in the WSL distribution where you're running your .NET Aspire application, or create a symbolic link to the Podman executable in a directory that's in your PATH (such as `/usr/local/bin`).
+
+- **Using shell aliases**: If you have a shell alias like `alias podman='podman-remote-static-linux_amd64'` in your `~/.bash_aliases` or similar file, .NET Aspire won't be able to find the container runtime.
+
+  **Solution**: Instead of using an alias, create a symbolic link or add the directory containing the Podman executable to your PATH:
+
+  ```bash
+  # Option 1: Create a symbolic link
+  sudo ln -s /path/to/podman-remote-static-linux_amd64 /usr/local/bin/podman
+
+  # Option 2: Add to PATH in your shell profile
+  echo 'export PATH="/path/to/podman/directory:$PATH"' >> ~/.bashrc
+  source ~/.bashrc
+  ```
+
+**Verify your setup**: You can verify that Podman is correctly configured by running:
+
+```bash
+which podman
+podman --version
+```
+
+Both commands should succeed and return valid results before running your .NET Aspire application.
+
+> [!TIP]
+> If you encounter issues with Podman in WSL environments, see [Container runtime 'podman' could not be found in WSL](../troubleshooting/podman-wsl-not-found.md) for specific troubleshooting guidance.
+
 ## .NET Aspire dashboard
 
 .NET Aspire templates that expose the [app host](app-host-overview.md) project also include a useful developer [dashboard](dashboard/overview.md) that's used to monitor and inspect various aspects of your app, such as logs, traces, and environment configurations. This dashboard is designed to improve the local development experience and provides an overview of the overall state and structure of your app.

docs/get-started/migrate-from-docker-compose.md

@@ -367,6 +367,7 @@ When migrating from Docker Compose to .NET Aspire, you might encounter some comm
 
 - [Docker Compose FAQ](https://docs.docker.com/compose/faq/)
 - [Container runtime unhealthy](../troubleshooting/container-runtime-unhealthy.md)
+- [Container runtime 'podman' could not be found in WSL](../troubleshooting/podman-wsl-not-found.md)
 - [.NET Aspire dashboard overview](../fundamentals/dashboard/overview.md)
 
 ## Next steps

docs/toc.yml

@@ -498,6 +498,9 @@ items:
     href: troubleshooting/name-is-already-in-use.md
   - name: Container runtime appears to be unhealthy
     href: troubleshooting/container-runtime-unhealthy.md
+  - name: Container runtime 'podman' could not be found in WSL
+    displayName: podman,wsl,container runtime,linux
+    href: troubleshooting/podman-wsl-not-found.md
   - name: The connection string is missing
     href: troubleshooting/connection-string-missing.md
   - name: Ask questions on Discord

docs/troubleshooting/podman-wsl-not-found.md

@@ -0,0 +1,89 @@
+---
+title: Container runtime 'podman' could not be found in WSL
+description: Learn how to troubleshoot the error "Container runtime 'podman' could not be found" when using Podman in Windows Subsystem for Linux (WSL).
+ms.date: 08/04/2025
+---
+
+# Container runtime 'podman' could not be found in WSL
+
+.NET Aspire requires a container runtime to be available in the system PATH. This article describes how to resolve issues when Podman isn't found in Windows Subsystem for Linux (WSL) environments.
+
+## Symptoms
+
+When starting your .NET Aspire application, you see an error message similar to:
+
+```Output
+Container runtime 'podman' could not be found. The error from the container runtime check was: exec: "podman": executable file not found in $PATH
+```
+
+This occurs even though running `podman images` or other Podman commands work successfully in your WSL terminal.
+
+## Cause
+
+This issue occurs in WSL environments when:
+
+- Podman is installed in a separate WSL distribution than where your .NET Aspire application is running.
+- You're using shell aliases instead of having the actual Podman executable in your PATH.
+- The Podman executable isn't available in the system PATH that .NET Aspire searches.
+
+.NET Aspire resolves container runtimes by searching for the executable in the system PATH. Shell aliases (like those defined in `~/.bash_aliases`) aren't recognized during this process.
+
+## Solution
+
+Choose one of the following solutions:
+
+### Install Podman in the current WSL distribution
+
+Install Podman directly in the WSL distribution where you're running your .NET Aspire application:
+
+```bash
+# For Ubuntu/Debian-based distributions
+sudo apt update
+sudo apt install -y podman
+```
+
+For other distributions, see [Install Podman on Linux](https://podman.io/docs/installation#installing-on-linux).
+
+### Create a symbolic link
+
+If you have Podman installed elsewhere, create a symbolic link:
+
+```bash
+# Find where Podman is installed
+which podman-remote-static-linux_amd64
+
+# Create a symbolic link in a directory that's in your PATH
+sudo ln -s /path/to/podman-remote-static-linux_amd64 /usr/local/bin/podman
+```
+
+### Add Podman directory to PATH
+
+Add the directory containing the Podman executable to your PATH:
+
+```bash
+# Add to your shell profile
+echo 'export PATH="/path/to/podman/directory:$PATH"' >> ~/.bashrc
+source ~/.bashrc
+```
+
+## Verify the solution
+
+Confirm that Podman is correctly configured:
+
+```bash
+# Check that Podman is in your PATH
+which podman
+
+# Verify Podman is working
+podman --version
+
+# Test that Podman can list containers
+podman ps
+```
+
+All commands should succeed before running your .NET Aspire application.
+
+## See also
+
+- [Container runtime setup](../fundamentals/setup-tooling.md#container-runtime)
+- [Container runtime appears to be unhealthy](container-runtime-unhealthy.md)