[GitHub Discussions] Docker & Container documentation gaps

[davidfowl]

Summary

Based on analysis of 820 GitHub discussions from dotnet/aspire.

Question counts:

Topic	Questions
Docker/Containers	156 total
Container Build	40+
Volumes/Persistence	25+
Docker Compose	20+
Registry	15+
Networking	20+

---

Gaps in Existing Docs

1. ✅ Docker Compose Publishing - WELL DOCUMENTED

Docs exist: docker-integration Γ£à comprehensive coverage

The doc covers:

• AddDockerComposeEnvironment and PublishAsDockerComposeService
• aspire publish, aspire do prepare-{name}, aspire deploy
• Environment file customization
• Container registry configuration (AddContainerRegistry)
• GitHub Actions workflow example
• Image push with aspire do push

Remaining questions:

• when build container images for aspire project via cli dotnet publish, it seems the containers created are not the same across Windows and Linux aspire#14008: Container images different across Windows and Linux

What might be missing:

• Cross-platform build consistency troubleshooting
• Platform architecture configuration details

---

2. ⚠️ Container Build Troubleshooting

Docs exist: docker-integration, add-dockerfiles-to-your-app-model Γ£à

Discussions:

• when build container images for aspire project via cli dotnet publish, it seems the containers created are not the same across Windows and Linux aspire#14008: Container images different across Windows and Linux
• Aspire CLI not include Docker Container when take build. aspire#10949: Aspire CLI not include Docker Container when take build
• SqlServer container rebuilt every run using WithDockerfile(..) and .WithLifetime(ContainerLifetime.Persistent) aspire#8278: SqlServer container rebuilt every run

What's missing:

• Cross-platform container build troubleshooting
• Container inclusion/exclusion configuration
• Rebuild behavior control (avoiding unwanted rebuilds)

---

3. ✅ Volume/Persistence - WELL DOCUMENTED

Docs exist: persist-aspire-project-data-using-volumes-or-bind-mounts, persistent-container-lifetimes Γ£à

Remaining questions:

• Remove agent PR polling from test-scenario workflow aspire#12393: WithDataVolume Key Collision with AddDockerComposeEnvironment
• Ability to restore a backup to a postgres container? aspire#12906: Ability to restore a backup to a postgres container?

What might be missing:

• Volume naming conflict resolution
• Database backup/restore with volumes

---

4. ✅ Container Networking - WELL DOCUMENTED

Docs exist: inner-loop-networking-overview Γ£à comprehensive

The doc covers:

• Container bridge networks (aspire-session-network, aspire-persistent-network)
• DNS-based service discovery between containers
• host.docker.internal behavior
• Container-to-container communication

Remaining questions:

• Using resources with endpoint different from localhost. aspire#14003: Using resources with endpoint different from localhost

What might be missing:

• Container-to-localhost SQL Server specific patterns
• External network exposure (0.0.0.0 binding)

---

5. ⚠️ Alternative Runtimes

Docs exist: None for Podman or alternative runtimes

Discussions:

• It is possible to run .NET Aspire without Docker/Podman? Maybe using Kaniko/Skaffold? aspire#6445: Run .NET Aspire without Docker/Podman? (Kaniko/Skaffold)
• How to run Aspire in a .NET SDK container without docker client? aspire#12204: Run in .NET SDK container without docker client

What's needed:

• Podman support documentation
• Running without Docker scenarios
• Alternative container runtime support status

---

Data Source

• GitHub Discussions: 820 total
• Docker/Container-related: 156 discussions
• Date range: Project inception - February 2026
• Verified against: aspire-list_docs (12 container/docker docs), aspire-get_doc for detailed review