Skip to content

Add WSL-specific Podman documentation and troubleshooting guide #4190

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from

Conversation

Copilot
Copy link
Contributor

@Copilot Copilot AI commented Aug 4, 2025

This PR addresses a common issue where .NET Aspire applications fail to find Podman in Windows Subsystem for Linux (WSL) environments, even when Podman commands work correctly in the terminal.

Problem

Users encounter the error:

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 in WSL environments where:

  • Podman is installed in a separate WSL distribution
  • Users rely on shell aliases (like alias podman='podman-remote-static-linux_amd64' in ~/.bash_aliases)
  • The podman executable isn't directly available in the system PATH

Solution

The PR adds comprehensive documentation to help users properly configure Podman in WSL environments:

  1. Enhanced Container Runtime section in setup-tooling.md with WSL-specific considerations explaining:

    • Why shell aliases don't work with .NET Aspire's executable resolution
    • Solutions for cross-distribution Podman setups
    • Proper PATH configuration and symbolic link alternatives
    • Verification steps
  2. New troubleshooting document podman-wsl-not-found.md following the standard troubleshooting template pattern with:

    • Clear error symptoms and root cause analysis
    • Multiple solution approaches (local installation, symbolic links, PATH modification)
    • Step-by-step verification instructions
    • WSL-specific considerations
  3. TOC entry added to make the troubleshooting guide discoverable in the documentation navigation

  4. Cross-references added to connect users to the troubleshooting guide from relevant documentation sections

The documentation clearly explains that .NET Aspire resolves container runtimes by searching the system PATH for executables, and shell aliases aren't recognized during this process.

Fixes #1651.


💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.


Internal previews

📄 File 🔗 Preview link
docs/fundamentals/setup-tooling.md docs/fundamentals/setup-tooling
docs/get-started/migrate-from-docker-compose.md docs/get-started/migrate-from-docker-compose
docs/toc.yml docs/toc
docs/troubleshooting/podman-wsl-not-found.md docs/troubleshooting/podman-wsl-not-found

@Copilot Copilot AI changed the title [WIP] Podman from WSL not found Add WSL-specific Podman documentation and troubleshooting guide Aug 4, 2025
@Copilot Copilot AI requested a review from IEvangelist August 4, 2025 20:51
Copilot finished work on behalf of IEvangelist August 4, 2025 20:51
@Copilot Copilot AI requested a review from IEvangelist August 5, 2025 13:42
Copilot finished work on behalf of IEvangelist August 5, 2025 13:42
@IEvangelist IEvangelist marked this pull request as ready for review August 5, 2025 13:59
@IEvangelist IEvangelist enabled auto-merge (squash) August 5, 2025 13:59
@IEvangelist IEvangelist requested a review from adegeo August 5, 2025 13:59
Copy link
Member

@IEvangelist IEvangelist left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We need a TOC entry for this new article.

@IEvangelist
Copy link
Member

Hey @copilot, we need a TOC entry for this new article. Also, can this article be written according to the troubleshooting template at https://review.learn.microsoft.com/en-us/help/patterns/level4/global-problem-resolution-template?branch=main

auto-merge was automatically disabled August 6, 2025 16:24

Head branch was pushed to by a user without write access

Copy link
Contributor Author

Copilot AI commented Aug 6, 2025

We need a TOC entry for this new article.

Added TOC entry for the new troubleshooting article. The entry is placed in the troubleshooting section near other container runtime related articles. Commit a0a76b1.

Hey @copilot, we need a TOC entry for this new article. Also, can this article be written according to the troubleshooting template at https://review.learn.microsoft.com/en-us/help/patterns/level4/glo...

Added TOC entry and restructured the article according to the troubleshooting template pattern. The article now follows a more concise structure with clear Symptoms, Cause, Solution, and verification sections similar to other troubleshooting articles in the docs. Commit a0a76b1.

@Copilot Copilot AI requested a review from IEvangelist August 6, 2025 16:25
Copilot finished work on behalf of IEvangelist August 6, 2025 16:25
@@ -0,0 +1,89 @@
---
title: Container runtime 'podman' could not be found in WSL
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot rewrite this article according to the template at https://review.learn.microsoft.com/en-us/help/patterns/level4/global-problem-resolution-template?branch=main

Make sure to set the appropriate topic type metadata.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Podman from WSL not found
3 participants