Skip to content

Add Docker Compose migration guide #3852

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Add Docker Compose migration guide #3852

wants to merge 2 commits into from

Conversation

Copilot
Copy link
Contributor

@Copilot Copilot AI commented Jun 18, 2025

This PR adds a comprehensive migration guide to help developers transition from Docker Compose to .NET Aspire. The guide addresses the issue raised in #936 where many people are trying to migrate from Docker Compose to .NET Aspire but lack guidance on how concepts translate between the two systems.

What's included

The new guide (docs/get-started/migrate-from-docker-compose.md) covers:

  • Conceptual differences between Docker Compose and .NET Aspire
  • Practical migration examples for common scenarios:
    • Multi-service web applications
    • Container-based services
    • Environment variables and configuration
    • Custom networks and volumes
  • Step-by-step migration strategy
  • Docker Compose publishing capabilities introduced in .NET Aspire 9.3
  • Troubleshooting tips and community resources

Example migration

The guide shows how to convert typical Docker Compose setups:

Docker Compose:

services:
  api:
    build: ./api
    depends_on:
      - database
  database:
    image: postgres:15
    environment:
      - POSTGRES_DB=myapp

.NET Aspire equivalent:

var builder = DistributedApplication.CreateBuilder(args);

var database = builder.AddPostgres("postgres")
    .WithEnvironment("POSTGRES_DB", "myapp")
    .AddDatabase("myapp");

var api = builder.AddProject<Projects.MyApp_Api>("api")
    .WithReference(database);

builder.Build().Run();

Changes made

  • Added new migration guide at docs/get-started/migrate-from-docker-compose.md
  • Updated docs/toc.yml to include the guide in the Get Started section with appropriate display keywords
  • All markdown formatting follows repository guidelines and passes linting

The guide is positioned in the "Get Started" section as it helps developers new to .NET Aspire understand how to transition from their existing Docker Compose workflows.

Fixes #936.


💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.


Internal previews

📄 File 🔗 Preview link
docs/get-started/migrate-from-docker-compose.md docs/get-started/migrate-from-docker-compose
docs/toc.yml docs/toc

Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>
@Copilot Copilot AI changed the title [WIP] Add a docker compose migration guide Add Docker Compose migration guide Jun 18, 2025
Copilot finished work on behalf of IEvangelist June 18, 2025 16:48
@Copilot Copilot AI requested a review from IEvangelist June 18, 2025 16:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Add a docker compose migration guide
2 participants