Aspire app lifecycle guide

This guide provides a high-level overview of the lifecycle phases of an Aspire application, from development through local deployment to production release. By using the same AppHost configuration across all phases, you ensure consistency and reduce configuration drift between environments. The example in this guide demonstrates how Aspire orchestrates containerized applications with persistent storage and CI/CD automation using the Docker Integration and GitHub.

App lifecycle

The Aspire application lifecycle consists of three main phases:

Each phase uses the same AppHost configuration but serves different purposes in the development and deployment workflows.

Example

The following example uses a C# AppHost, but the same lifecycle applies to TypeScript AppHosts.

Consider this example. You have a distributed application that consists of a Blazor web project that relies on a SQL Server database with a persistent data volume as well as a persistent writable file volume to capture user file uploads. You want to distribute your Blazor app as a Docker container image via the GitHub Container Registry. You need the Aspire.Hosting.Docker and Aspire.Hosting.SqlServer integrations.

var builder = DistributedApplication.CreateBuilder(args);
  
// Add Docker Compose environment
var compose = builder.AddDockerComposeEnvironment("volumemount-env")
    .WithProperties(env =>
    {
        env.DashboardEnabled = true;
    })
    .ConfigureComposeFile(composeFile =>
     {
         // Add the blazor file volume to the top-level volumes section
         composeFile.AddVolume(new Volume
         {
             Name = "volumemount-blazor-uploads",
            Driver = "local"
         });
     });
  
// Add container registry
var endpoint = builder.AddParameter("registry-endpoint");
var repository = builder.AddParameter("registry-repository");
builder.AddContainerRegistry("container-registry", endpoint, repository);
  
//Add SQL Server with data volume
var sqlPassword = builder.AddParameter("sqlserver-password", secret: true);
var sqlserver = builder.AddSqlServer("sqlserver", password: sqlPassword)
    .WithDataVolume("volumemount-sqlserver-data")
    .WithLifetime(ContainerLifetime.Persistent);   
  
var sqlDatabase = sqlserver.AddDatabase("sqldb");
  
//Add the Blazor web app with reference to the database
//Deploy as a docker image with a volume mount for user upload files 
var blazorweb = builder.AddProject<Projects.VolumeMount_BlazorWeb>("blazorweb")
        .WithExternalHttpEndpoints()
        .WithReference(sqlDatabase)
        .WaitFor(sqlDatabase)
        //Deploy the Web project as a Docker Compose service with a volume mount for files
        .PublishAsDockerComposeService((resource, service) =>
        {
            service.AddVolume(new Volume
            {
                Name = "volumemount-blazor-uploads",
                Source = "volumemount-blazor-uploads",
                Target = "/app/wwwroot/uploads",
                Type = "volume",
                ReadOnly = false
            });
  
            // Override the entrypoint to allow write permissions to the volume 
            // then run the default entrypoint as app user
            service.User = "root";
            service.Command = new List<string>
            {
                "/bin/sh",
                "-c",
                "chown -R app:app /app/wwwroot/uploads && chmod -R 755 /app/wwwroot/uploads && exec su app -c 'dotnet /app/VolumeMount.BlazorWeb.dll'"
            };
  
        });
  
builder.Build().Run();

Phase 1: Inner-Loop Development

What is aspire run?

The aspire run command starts your Aspire application in development mode. This is the inner-loop development experience where you write code, test changes, and debug your application locally.

When you run aspire run:

This command searches the current directory structure for AppHost projects to build and run:

aspire run

The console will display the dashboard URL with a login token:

Dashboard:  https://localhost:17244/login?t=9db79f2885dae24ee06c6ef10290b8b2
  
    Logs:  /home/vscode/.aspire/cli/logs/apphost-5932-2025-08-25-18-37-31.log
  
        Press CTRL+C to stop the apphost and exit.

In the example above, when resources start with the run command:

• SQL Server container starts in Docker with persistent volume
• Web project runs as a local process (not containerized)
• Database is automatically created and migrated (containerized)

Phase 2: Local Deployment

What is aspire deploy?

The aspire deploy command creates a fully containerized deployment of your application in the compute environment(s) you define. This simulates a production-like environment on your local machine. In this example, local containers and volumes are created on Docker Desktop using the Docker Integration. It requires all parameters to be set.

When you run aspire deploy Aspire will:

In this example, the following gets deployed:

Containers:

• aspire-volumemount-env - Docker Compose stack
• sqlserver - SQL Server with persistent data volume
• blazorweb - Blazor Web app with persistent file uploads volume
• volumemount-env-dashboard - Monitoring dashboard

Volumes:

• volumemount-sqlserver-data - Stores database files (.mdf, .ldf)
• volumemount-blazor-uploads - Stores user-uploaded images

You can login to your GitHub Container Registry before deploying.

export GITHUB_TOKEN=
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin
  
aspire deploy

Phase 3: Publish Release (CI/CD)

You can create a workflow that automates the process of building and pushing the image, and publishing of deployment artifacts using the Aspire CLI in a CI/CD pipeline. The Aspire CLI can be used to build your app, push images, and publish artifacts. This allows you to deploy the app later via standard Docker Compose.

In this example, the workflow runs on every push to main, does a checkout, and then performs these steps:

Step 1: Setup Environment

# Required for C# AppHost projects
- name: Setup .NET
  uses: actions/setup-dotnet@v4
  with:
    dotnet-version: '10.0.x'

Step 2: Install Aspire CLI

- name: Install Aspire CLI
  run: |
    echo "Installing Aspire CLI from install script..."
    curl -sSL https://aspire.dev/install.sh | bash
    echo "$HOME/.aspire/bin" >> $GITHUB_PATH

Step 3. Build App, Create & Push Image to GHCR

- name: Login to GHCR
  uses: docker/login-action@v3
  with:
    registry: ghcr.io
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}
  
- name: Build and Push images with Aspire
  env:
    Parameters__registry_endpoint: ghcr.io
    Parameters__registry_repository: your-org/your-repo
  run: aspire do push

The aspire do push command does the following:

• Analyzes your AppHost configuration
• Restores dependencies and builds the project
• Builds Docker container images for project resources
• Tags images with configured registry endpoint and repository
• Pushes images to GitHub Container Registry (ghcr.io)
• Uses parameters defined in AppHost.cs:
  • Environment Parameters__registry_endpoint maps to registry-endpoint parameter
  • Environment Parameters__registry_repository maps to registry-repository parameter

Step 4: Publish Docker Compose Artifacts

- name: Prepare Docker Compose with Aspire
  run: |
    aspire publish \
      --project VolumeMount.AppHost/VolumeMount.AppHost.csproj \
      --output-path ./aspire-output

The aspire publish command does the following:

• Analyzes your AppHost configuration
• Generates docker-compose.yaml file with all service definitions
• Creates .env template file for environment variables
• Packages configuration needed for deployment
• Outputs artifacts to ./aspire-output/ directory

Step 5: Upload Deployment Artifacts

- name: Upload Aspire artifacts
  uses: actions/upload-artifact@v4
  with:
    name: aspire-deployment-files
    path: ./aspire-output/
    retention-days: 30
    include-hidden-files: true

In this example, artifacts are available for download from the Actions workflow run for 30 days. Hidden files are included so that the .env file is also available in the artifacts.

Deploying to Production

After the workflow completes, you have everything needed for production deployment:

Lifecycle Summary

The AppHost is the single source of truth for your application architecture. Each phase above uses the exact same AppHost configuration. This eliminates configuration drift between development and deployment. It defines things your distributed application needs like:

• Services & Dependencies - Projects, containers, and their relationships
• Configuration - Connection strings, secrets, and parameters
• Volumes - Persistent storage for databases and files
• Networking - Endpoints, ports, and service communication
• Deployment - Container registry, image tags, and publish settings

For more information, see AppHost configuration.

Next steps

• Learn more about Service discovery
• Explore Telemetry options
• Understand Health checks