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.
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.
To bypass auto-detection and force a specific runtime, set the ASPIRE_CONTAINER_RUNTIME environment variable to docker or podman before invoking the Aspire CLI:
Terminal
ASPIRE_CONTAINER_RUNTIME=podmanaspiredeploy
When this variable is set, the chosen runtime is shown by aspire doctor with the reason (explicit configuration) and is honored even when both runtimes are running.
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.
Aspire provides a progressive deployment workflow for Docker Compose, allowing you to publish, prepare environments, and deploy in separate steps or all at once.
Publish the application
To generate Docker Compose files and artifacts without building container images, use the aspire publish command:
Terminal
aspirepublish
This command:
Generates a docker-compose.yaml from the AppHost
Generates a .env file with expected parameters (unfilled)
Outputs everything to the aspire-output directory
Prepare environment configurations
To prepare environment-specific configurations and build container images, use the aspire do prepare-{resource-name} command, where {resource-name} is the name of the Docker Compose environment resource:
Terminal
# For staging environment
aspiredoprepare-compose--environmentstaging
# For production environment
aspiredoprepare-compose--environmentproduction
These commands:
Generate a docker-compose.yaml from the AppHost
Generate environment-specific .env files with filled-in values
Build container images
Output everything to the aspire-output directory
Deploy to Docker Compose
To perform the complete deployment workflow in one step, use the aspire deploy command:
Terminal
aspiredeploy
This command:
Generates a docker-compose.yaml from the AppHost
Generates environment-specific .env files with filled-in values
Builds container images
Outputs everything to the aspire-output directory
Runs docker compose up -d --remove-orphans against the generated files
To stop and remove a running Docker Compose deployment, use the aspire destroy command:
Terminal
aspiredestroy
The command shows the resources that will be removed and prompts for confirmation. Once confirmed, it stops and removes all containers, networks, and volumes created by the Docker Compose deployment.
Docker Compose deployments support multiple environments through the --environment flag. Each environment produces its own .env.{environment} file with environment-specific parameter values, while sharing the same docker-compose.yaml.
Use the --environment flag to deploy the same application to different environments on the same or different Docker hosts:
Deploy to staging
aspiredeploy--environmentstaging
Deploy to production
aspiredeploy--environmentproduction
Each deployment:
Runs the AppHost with the specified environment, so builder.Environment.EnvironmentName reflects staging or production. Any environment-based branching in your AppHost applies automatically.
Generates an .env.staging or .env.production file with filled-in parameter values.
To generate artifacts without deploying, use aspire do prepare-{resource-name} with the --environment flag:
Prepare staging and production artifacts
aspiredoprepare-env--environmentstaging
aspiredoprepare-env--environmentproduction
This generates environment-specific .env files that you can deploy independently, for example from a CI pipeline that targets different Docker hosts per environment.
For more on how environments work across all deployment targets, see the
Environments guide. For command details on
prepare-* steps, see the CLI reference: aspire do.
Docker Compose deployments can build images from Dockerfiles that are generated by your AppHost. Use AddDockerfileBuilder to create a new container resource from a generated Dockerfile, or WithDockerfileBuilder to replace the image for an existing container resource with a generated Dockerfile build.
The generated Dockerfile is included with the Docker Compose output and is used when aspire do prepare-{resource-name} or aspire deploy builds container images.
The Docker hosting integration captures environment variables from your app model and includes them in a .env file. This ensures that all configuration is properly passed to the containerized services.
To customize the generated Docker Compose service for a specific resource, use the PublishAsDockerComposeService method. This is optional — all resources are automatically included in the Docker Compose output. Use this method only when you need to modify the generated service definition:
The configure callback receives the DockerComposeServiceResource and the generated Service object, allowing you to modify properties like labels, restart policy, container name, or other Docker Compose service settings. Use AsEnvironmentPlaceholder for values that should be written as Compose environment variable placeholders in the generated YAML and .env files.
Use GetHostAddressExpression when you need the host name that another Docker Compose service should use for an endpoint. In Docker Compose deployments, this expression resolves to the generated service name on the Compose network.
Container resources support an ImagePullPolicy that controls when the container runtime pulls an image. Use the WithImagePullPolicy extension method to set the policy on a container resource:
After configuring your container registry, use the aspire do push command to build and push your container images:
Terminal
aspiredopush
This command builds container images for all resources configured with a container registry, tags them with the appropriate registry path, and pushes them to the specified registry.
Before running this command, ensure you are authenticated to your container registry. For example, with GitHub Container Registry:
The following GitHub Actions workflow builds and pushes container images to GitHub Container Registry (GHCR):
.github/workflows/build-and-push.yml
name:Build and Push Images
on:
push:
branches:[main]
jobs:
build-and-push:
runs-on:ubuntu-latest
permissions:
contents:read
packages:write
steps:
-uses:actions/checkout@v4
-name:Setup .NET
uses:actions/setup-dotnet@v4
with:
dotnet-version:'10.0.x'
-name:Install Aspire CLI
run:|
curl -sSL https://aspire.dev/install.sh | bash
echo "$HOME/.aspire/bin" >> $GITHUB_PATH
-name:Output Aspire CLI version
run:aspire --version
-name:Log in to GitHub Container Registry
uses:docker/login-action@v3
with:
registry:ghcr.io
username:${{ github.actor }}
password:${{ secrets.GITHUB_TOKEN }}
-name:Build and push images
env:
REGISTRY_ENDPOINT:ghcr.io
REGISTRY_REPOSITORY:${{ github.repository }}
run:aspire do push
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.
Aspire