Skip to main content

The Aspire Manifest

Aspire isn't opinionated about deployment. What it does instead is allow you to generate a manifest file that describes everything about your system. This manifest can be consumed by various deployment tools to automate infrastructure provisioning and deployments.

The manifest is a JSON file that represents your entire application's topology—all services, resources, dependencies, and configurations defined in your AppHost.

Generating the Manifest​

You can generate the Aspire manifest using either the Aspire CLI or the .NET CLI.

Using the Aspire CLI​

The Aspire CLI provides a dedicated publish command for generating the manifest:

aspire publish

By default, this generates the manifest in the ./aspire-manifest directory. You can specify a custom output path:

aspire publish --output-path ./my-manifest

Using the .NET CLI​

Alternatively, you can use the .NET CLI directly:

dotnet run --project <path-to-apphost> -- --publisher manifest --output-path ./aspire-manifest

For example:

dotnet run --project src/Dometrain.Aspire.AppHost -- --publisher manifest --output-path ./aspire-manifest

Understanding the Manifest​

The generated manifest.json file contains a complete description of your application:

  • Projects: All .NET projects in your application (APIs, worker services, etc.)
  • Containers: Docker containers (PostgreSQL, Redis, RabbitMQ, etc.)
  • Connections: How services connect to each other and to resources
  • Environment variables: Configuration values and connection strings
  • Dependencies: The startup order and dependencies between resources

This machine-readable format allows deployment tools to understand your application's requirements without needing to parse your AppHost code.

Using the Manifest for Deployment​

The manifest serves as input for various deployment targets:

Azure Container Apps​

When deploying to Azure Container Apps using azd (Azure Developer CLI), the manifest is automatically generated and used to:

  • Provision Azure resources (Container Apps, Cosmos DB, Redis, etc.)
  • Configure networking and service-to-service communication
  • Set up environment variables and secrets
  • Establish dependencies between resources

Kubernetes​

Tools like Aspirate or custom deployment pipelines can transform the manifest into Kubernetes manifests (Deployments, Services, ConfigMaps, etc.).

Docker Compose​

The manifest can be transformed into a docker-compose.yml file for local testing or simple deployments.

Generating Docker Compose Files with Aspire CLI​

The Aspire CLI can generate Docker Compose files directly from your AppHost project, making it easy to run your entire application stack using Docker Compose.

Step 1: Install the Docker Hosting Package​

Before you can generate Docker Compose files, you need to add the Docker hosting package to your AppHost project:

dotnet add package Aspire.Hosting.Docker

This package provides the Docker Compose publisher that transforms your Aspire manifest into a docker-compose.yml file.

Step 2: Add Docker Compose Environment to AppHost​

In your AppHost's Program.cs, add a call to AddDockerComposeEnvironment before defining your resources:

var builder = DistributedApplication.CreateBuilder(args);

// Enable Docker Compose publishing
builder.AddDockerComposeEnvironment("cloud-native-workshop");

// Your existing resources
var mainDb = builder.AddPostgres("main-db")
    .WithDataVolume()
    .WithLifetime(ResourceLifetime.Persistent)
    .AddDatabase("dometrain");

var carts = builder.AddAzureCosmosDB("cosmosdb")
    .RunAsPreviewEmulator()
    .WithDataExplorer()
    .AddDatabase("cartdb")
    .AddContainer("carts", partitionKeyPath: "/pk");

var redis = builder.AddRedis("redis")
    .WithLifetime(ResourceLifetime.Persistent)
    .WithRedisInsight();

var rabbitmq = builder.AddRabbitMQ("rabbitmq")
    .WithLifetime(ResourceLifetime.Persistent)
    .WithManagementPlugin();

builder.AddProject<Projects.Dometrain_Monolith_Api>("dometrain-api")
    .WithReplicas(5)
    .WithReference(redis)
    .WithReference(mainDb)
    .WithReference(carts)
    .WithReference(rabbitmq);

builder.Build().Run();

The AddDockerComposeEnvironment method takes a name parameter that will be used as the Docker Compose project name.

Step 3: Generate Docker Compose Files​

To generate a docker-compose.yml file, use the aspire publish command with the -p docker-compose option:

aspire publish -p docker-compose

This command:

  1. Analyzes your AppHost project
  2. Generates the Aspire manifest
  3. Transforms the manifest into a docker-compose.yml file
  4. Outputs the file to the current directory

Custom Output Path​

You can specify a custom output directory with the -o or --output-path option:

aspire publish -p docker-compose -o ./docker-output

Interactive Mode​

You can also run aspire publish without parameters to use the interactive wizard that will prompt you to select the publisher type:

aspire publish

Then select "docker-compose" from the available options.

What Gets Generated​

The generated Docker Compose file includes:

  • Services: All containerized services (your .NET projects as containers)
  • Infrastructure: PostgreSQL, Redis, RabbitMQ, and other container resources
  • Networks: Proper networking configuration for service-to-service communication
  • Environment variables: Connection strings and configuration
  • Dependencies: Service startup order using depends_on

Running with Docker Compose​

Once generated, navigate to the output directory and run your entire application stack:

docker compose up

Or if you specified a custom output path:

cd ./docker-output
docker compose up

This starts all services and infrastructure components defined in your AppHost.

Limitations and Considerations​

Cloud-managed resources: Azure-specific resources that don't have containerized equivalents won't be included in the Docker Compose file. However:

  • Cosmos DB with Preview Emulator: Since our workshop uses .RunAsPreviewEmulator(), Cosmos DB will be included as a container in the generated Docker Compose file
  • Azure Service Bus: Would require a connection string to an Azure instance or an alternative like RabbitMQ
  • Azure Key Vault: Would need to be replaced with environment variables or a secrets management solution

PostgreSQL, Redis, and RabbitMQ: These will all be included in the Docker Compose file since they have official Docker images.

Project replicas: The .WithReplicas(5) configuration may not be fully supported in the Docker Compose output. You may need to manually adjust the compose file if you need multiple instances of a service.

Next Steps​

In the following sections, we'll explore how to deploy our Aspire application to Azure using the manifest and Azure Developer CLI (azd).