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/troubleshooting/podman-wsl-not-found.md

@@ -0,0 +1,102 @@
+---
+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
+
+When using Podman with Windows Subsystem for Linux (WSL), you might encounter issues where .NET Aspire can't find the Podman container runtime, even though Podman commands work in your terminal.
+
+## 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.
+
+## Root cause
+
+This issue typically occurs in WSL environments when:
+
+1. **Podman is installed in a separate WSL distribution** than where your .NET Aspire application is running
+2. **You're using shell aliases** instead of having the actual Podman executable in your PATH
+3. **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.
+
+## Solutions
+
+### Solution 1: Install Podman in the current WSL distribution
+
+The most straightforward solution is to 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: https://podman.io/docs/installation#installing-on-linux
+```
+
+### Solution 2: Create a symbolic link
+
+If you have Podman installed elsewhere and want to make it available in your current distribution:
+
+```bash
+# Find where Podman is installed (example path)
+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
+```
+
+### Solution 3: Add to PATH
+
+If you know the directory containing the Podman executable, add it to your PATH:
+
+```bash
+# Add to your shell profile (example for bash)
+echo 'export PATH="/path/to/podman/directory:$PATH"' >> ~/.bashrc
+source ~/.bashrc
+```
+
+### Solution 4: Use environment variable
+
+Set the `ASPIRE_CONTAINER_RUNTIME` environment variable to help .NET Aspire locate Podman:
+
+```bash
+export ASPIRE_CONTAINER_RUNTIME=podman
+```
+
+## Verify the solution
+
+After applying any of the solutions above, verify 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 (should not error)
+podman ps
+```
+
+All commands should succeed before running your .NET Aspire application.
+
+## Additional considerations
+
+- **Aliases don't work**: Shell aliases like `alias podman='podman-remote-static-linux_amd64'` won't be recognized by .NET Aspire's executable resolution process.
+- **Distribution isolation**: Each WSL distribution has its own filesystem and installed packages. If you switch distributions, you might need to reconfigure Podman.
+- **Permission issues**: Ensure that the user running the .NET Aspire application has permission to execute the Podman binary.
+
+## See also
+
+- [Container runtime setup](../fundamentals/setup-tooling.md#container-runtime)
+- [Install Podman on Linux](https://podman.io/docs/installation#installing-on-linux)
+- [Container runtime appears to be unhealthy](container-runtime-unhealthy.md)