Docker Infrastructure Fallback
Relevant source files
The following files were used as context for generating this wiki page:
The Docker Infrastructure Fallback system provides a secondary mechanism for provisioning essential middleware, specifically RabbitMQ, when .NET Aspire orchestration is not utilized or during CI/CD workflows. While the primary orchestration for the project has been migrated to .NET Aspire (Phase 6), the project maintains a docker-compose.yml and supporting scripts to ensure developer productivity and environment stability.
Sources: claude.md:144-147, scripts/DOCKER_AUTOSTART_FIX.md:164-168
System Architecture
The fallback system is built around a PowerShell-based check-and-start mechanism integrated into the MSBuild pipeline. It ensures that required containers are running before the .NET build completes, preventing runtime failures due to missing infrastructure.
Execution Flow
When a build is initiated, the system checks for the existence of Docker and the state of the RabbitMQ container. If Docker is not running, the build fails fast with an actionable error message rather than hanging.
The flow ensures that Docker Desktop is active and RabbitMQ is ready before allowing the build to proceed.
Sources: scripts/DOCKER_AUTOSTART_FIX.md:131-140, scripts/ensure-docker.ps1:12-40
Core Components
1. ensure-docker.ps1
This script serves as the primary controller for the fallback infrastructure. It handles:
- Validation: Confirms Docker CLI is in the PATH and the Docker Desktop daemon is active.
- Idempotency: Skips the startup process if the
ddd-rabbitmqcontainer is already running. - Orchestration: Executes
docker-compose up -dto provision missing services. - Health Monitoring: Implements a configurable polling loop to wait for container readiness.
Sources: scripts/ensure-docker.ps1:1-60
2. MSBuild Integration (Directory.Build.targets)
The fallback is triggered via a custom MSBuild target that executes before the Build target. It includes a hard timeout to prevent indefinite hangs in non-interactive environments like CI/CD.
| Feature | Implementation | Description |
|---|---|---|
| Fail Fast | Immediate Exit | Removes interactive prompts (ReadKey) to prevent build hangs. |
| Timeouts | 90s (MSBuild) | Sets a hard limit on the PowerShell execution time. |
| Conditional | SKIP_DOCKER_CHECK | Environment variable to bypass infrastructure checks. |
Sources: scripts/DOCKER_AUTOSTART_FIX.md:11-30, scripts/DOCKER_AUTOSTART_FIX.md:66-78
Configuration and Usage
The fallback system can be tuned via parameters passed to the script or environment variables set in the shell.
Script Parameters
The ensure-docker.ps1 script supports the following parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
TimeoutSeconds | int | 60 | Maximum time to wait for a "healthy" status. |
SkipHealthCheck | switch | false | If set, the script exits immediately after starting the container. |
Sources: scripts/ensure-docker.ps1:7-10
Manual Control
Developers can manually trigger or bypass the fallback infrastructure:
- Bypass Check: Set
$env:SKIP_DOCKER_CHECK = "1"before runningdotnet build. - Manual Start: Execute
.\scripts\ensure-docker.ps1directly from PowerShell.
Sources: scripts/DOCKER_AUTOSTART_FIX.md:86-110
Relationship with .NET Aspire
In the current project phase, .NET Aspire is the primary orchestrator. As defined in Aspire.AppHost/AppHost.cs, Aspire manages RabbitMQ with a management plugin and provides durable data volumes for the main development slot.
// Aspire.AppHost/AppHost.cs
var rabbitMq = builder.AddRabbitMQ("messaging", password: messagingPassword)
.WithManagementPlugin();
if (slot == 1)
{
rabbitMq.WithDataVolume();
}
The Docker Infrastructure Fallback remains crucial for scenarios where the AppHost is not being used, such as running individual WebApis (Scheduling or Billing) directly via dotnet run or within automated testing pipelines.
Sources: Aspire.AppHost/AppHost.cs:113-124, claude.md:144-147
Conclusion
The Docker Infrastructure Fallback ensures that the project's event-driven architecture, which relies heavily on RabbitMQ for integration events, remains functional across diverse development environments. By shifting from blocking interactive prompts to a "fail-fast" script with MSBuild timeouts, the system provides a robust safety net that complements the modern .NET Aspire orchestration.
Sources: scripts/DOCKER_AUTOSTART_FIX.md:155-160, scripts/ensure-docker.ps1:68-70