From 3434818d8949443994277fba1dfcf48604347ad0 Mon Sep 17 00:00:00 2001 From: "aspire-repo-bot[bot]" <268009190+aspire-repo-bot[bot]@users.noreply.github.com> Date: Tue, 28 Apr 2026 17:36:23 +0000 Subject: [PATCH] docs: add Podman support for Docker Compose deployment (aspire#16074) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Document Podman as a supported container runtime for Docker Compose deploys - Describe auto-detection logic (parallel probe, prefer running, Docker tiebreaker) - Add Podman-specific behavior note (podman-compose / service discovery) - Document breaking change: IContainerRuntime → IContainerRuntimeResolver - Update aspire doctor docs to reflect multi-runtime reporting Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../docs/deployment/docker-compose.mdx | 47 ++++++++++++++++++- .../reference/cli/commands/aspire-doctor.mdx | 14 ++++-- 2 files changed, 56 insertions(+), 5 deletions(-) diff --git a/src/frontend/src/content/docs/deployment/docker-compose.mdx b/src/frontend/src/content/docs/deployment/docker-compose.mdx index ecd44ed01..fa66fc04b 100644 --- a/src/frontend/src/content/docs/deployment/docker-compose.mdx +++ b/src/frontend/src/content/docs/deployment/docker-compose.mdx @@ -1,12 +1,12 @@ --- title: Deploy to Docker Compose -description: Learn how to publish and deploy your Aspire application using Docker Compose. +description: Learn how to publish and deploy your Aspire application using Docker Compose with Docker or Podman. --- import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components'; import LearnMore from '@components/LearnMore.astro'; -Docker Compose is a deployment target for Aspire applications. When you add a Docker Compose environment to your AppHost, Aspire generates Docker Compose files, environment variable configurations, and container images from your app model. You can then deploy these artifacts to any machine running Docker. +Docker Compose is a deployment target for Aspire applications. When you add a Docker Compose environment to your AppHost, Aspire generates Docker Compose files, environment variable configurations, and container images from your app model. You can then deploy these artifacts to any machine running Docker or Podman. +## Container runtime support + +Aspire supports both **Docker** and **Podman** as container runtimes for Docker Compose deployments. Podman is popular in security-conscious, daemonless, and rootless environments. Aspire automatically detects and uses the best available runtime — no additional configuration is required. + +### Auto-detection + +At deploy time, Aspire probes Docker and Podman in parallel and selects the active runtime using the following priority: + +1. A runtime that is **running** (daemon active) is preferred over one that is merely installed. +2. If both runtimes are running, **Docker is preferred** as the tiebreaker. +3. The detected runtime is cached for the lifetime of the operation. + +This matches the detection logic used by DCP (the local orchestration layer), so the same runtime is used for both local development and deployment. + + + +### Podman-specific behavior + +When Podman is the active runtime, Aspire uses `podman-compose` (or the Docker Compose v2 provider for Podman) for `compose up` / `compose down` operations. Service discovery uses `podman ps --filter label=...`, which is compatible with both `podman-compose` (Python) and Docker Compose v2 providers. + ## Prerequisites To deploy with Docker Compose, add a Docker Compose environment resource to your AppHost using `AddDockerComposeEnvironment`: @@ -537,11 +560,31 @@ jobs: This workflow checks out your code, sets up .NET and installs the Aspire CLI, authenticates to GHCR using the built-in `GITHUB_TOKEN`, and builds and pushes container images using `aspire do push`. +## Breaking change: IContainerRuntime → IContainerRuntimeResolver + +In Aspire 13.3, the container runtime abstraction was updated to support async auto-detection. If you have custom hosting extensions or internal code that directly resolved `IContainerRuntime` from the DI container, you must now resolve `IContainerRuntimeResolver` instead and call `ResolveAsync()` to obtain the active `IContainerRuntime`: + +```csharp +// Before (no longer works) +var runtime = services.GetRequiredService(); + +// After +var resolver = services.GetRequiredService(); +var runtime = await resolver.ResolveAsync(); +``` + + + ## See also - [Docker integration](/integrations/compute/docker/) - [Pipelines and app topology](/deployment/pipelines/) - [Deploy your first Aspire app](/get-started/deploy-first-app/) +- [aspire doctor command](/reference/cli/commands/aspire-doctor/) - [`Aspire.Hosting.Docker` C# API reference](https://aspire.dev/reference/api/csharp/aspire.hosting.docker/) - [`Aspire.Hosting.Docker` TypeScript API reference](https://aspire.dev/reference/api/typescript/aspire.hosting.docker/) - [Working with GitHub Container Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry) diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-doctor.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-doctor.mdx index 3919f459a..58a4829a2 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-doctor.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-doctor.mdx @@ -34,7 +34,7 @@ The `aspire doctor` command runs a series of diagnostic checks to verify that yo This command is useful for troubleshooting when you encounter issues with Aspire or when setting up a new development environment. The checks are grouped by category: - **SDK checks**: Verifies .NET SDK installation and version requirements -- **Container checks**: Validates container runtime (Docker/Podman) availability and configuration +- **Container checks**: Validates container runtime (Docker and/or Podman) availability, running status, and version. Reports which runtime is active and why (explicit configuration, auto-detected default, or only runtime running) - **Environment checks**: Validates environment variables and other settings, including the JavaScript toolchain required by TypeScript AppHosts (npm, pnpm, Yarn, or Bun) The command displays results with clear status indicators: @@ -92,8 +92,8 @@ SDK ✓ Aspire templates are available Container Runtime -✓ Docker is installed and running -✓ Docker Compose is available +✓ Docker 27.3.1 is installed and running [active — preferred when both runtimes are available] +✓ Podman 5.3.0 is installed (not running) Environment ✓ ASPNETCORE_ENVIRONMENT is set correctly @@ -101,6 +101,14 @@ Environment Summary: 5 passed, 0 warnings, 0 failed ``` +When only Podman is available: + +```bash title="Aspire CLI" +Container Runtime +✓ Podman 5.3.0 is installed and running [active — only runtime running] +✗ Docker is not installed +``` + ## Exit codes The command returns the following exit codes: