Edit

Share via

Aspire Docker hosting integration

Includes: Hosting integration included Hosting integration only — Client integration not included Client integration not included

The Aspire Docker hosting integration enables you to deploy your Aspire applications using Docker Compose. This integration models Docker Compose environments as compute resources that can host your application services. When you use this integration, Aspire generates Docker Compose files that define all the services, networks, and volumes needed to run your application in a containerized environment. It supports generating Docker Compose files from your app model for deployment, orchestrating multiple services, including an Aspire dashboard for telemetry visualization, configuring environment variables and service dependencies, and managing container networking and service discovery.

Hosting integration

The Docker hosting integration is available in the 📦 Aspire.Hosting.Docker NuGet package.

dotnet add package Aspire.Hosting.Docker

For more information, see dotnet add package or Manage package dependencies in .NET applications.

Add Docker Compose environment resource

The following example demonstrates how to add a Docker Compose environment to your app model using the AddDockerComposeEnvironment method:

var builder = DistributedApplication.CreateBuilder(args);

// Add a Docker Compose environment
var compose = builder.AddDockerComposeEnvironment("compose");

// Add your services to the Docker Compose environment
var cache = builder.AddRedis("cache")
                   .PublishAsDockerComposeService((resource, service) =>
                   {
                       service.Name = "cache";
                   });

var apiService = builder.AddProject<Projects.ApiService>("apiservice")
                        .PublishAsDockerComposeService((resource, service) =>
                        {
                            service.Name = "api";
                        });

var webApp = builder.AddProject<Projects.WebApp>("webapp")
                    .WithReference(cache)
                    .WithReference(apiService)
                    .PublishAsDockerComposeService((resource, service) =>
                    {
                        service.Name = "web";
                    });

builder.Build().Run();

The preceding code:

  • Creates a Docker Compose environment named compose.
  • Adds a Redis cache service that will be included in the Docker Compose deployment.
  • Adds an API service project that will be containerized and included in the deployment.
  • Adds a web application that references both the cache and API service.
  • Configures all services to be published as Docker Compose services using PublishAsDockerComposeService.

Tip

With the compose variable assigned, you can pass that to the WithComputeEnvironment API to disambiguate compute resources for solutions that define more than one. Otherwise, the compose variable isn't required.

Add Docker Compose environment resource with properties

You can configure various properties of the Docker Compose environment using the WithProperties method:

builder.AddDockerComposeEnvironment("compose")
       .WithProperties(env =>
       {
           env.DefaultContainerRegistry = "myregistry.azurecr.io";
           env.DefaultNetworkName = "my-network";
           env.BuildContainerImages = true;
       });

Add Docker Compose environment resource with compose file

You can customize the generated Docker Compose file using the ConfigureComposeFile method:

builder.AddDockerComposeEnvironment("compose")
       .ConfigureComposeFile(composeFile =>
       {
           composeFile.Networks.Add("custom-network", new()
           {
               Driver = "bridge"
           });
       });

Add Aspire dashboard resource to environment

The Docker hosting integration includes an Aspire dashboard for telemetry visualization. You can configure or disable it using the WithDashboard method:

// Enable dashboard with custom configuration
builder.AddDockerComposeEnvironment("compose")
       .WithDashboard(dashboard =>
       {
           dashboard.WithHostPort(8080)
                    .WithForwardedHeaders(enabled: true);
       });

// Disable dashboard
builder.AddDockerComposeEnvironment("compose")
       .WithDashboard(enabled: false);

The WithHostPort method configures the port used to access the Aspire dashboard from a browser. The WithForwardedHeaders(IResourceBuilder<DockerComposeAspireDashboardResource>, Boolean) method enables forwarded headers processing when the dashboard is accessed through a reverse proxy or load balancer.

Publishing and deployment

To deploy your application using Docker Compose, use the aspire publish:

aspire publish -o docker-compose-artifacts

For more information, see aspire publish command reference.

This command generates Docker Compose files and all necessary artifacts in the specified output directory. The generated files include:

  • docker-compose.yml: The main Docker Compose file defining all services.
  • docker-compose.override.yml: Override file for development-specific settings.
  • .env: Environment variables file.
  • Service-specific configuration files and scripts.

After publishing, you can deploy your application using Docker Compose:

cd docker-compose-artifacts
docker compose up -d

Environment variables

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.

Next steps