To free onboarding developers from the nightmare of multi-day environment setup, BitzOrcas.Modern adopts .NET Aspire AppHost as the primary local development entrypoint. Instead of manually configuring local SQL Server or Redis instances, a single command orchestrates production-aligned container topologies and application services inside Docker.

Local Aspire Orchestration Topology & Ports

Verified Port Mapping & Service Matrix

The authoritative source of truth for ports is src/Hosts/BitzOrcas.AppHost/LocalDevPorts.cs and each project’s launchSettings.json. AppHost pins only two host ports: SQL Server 14333 and the orchestrator frontend 5860. All other backing resources are assigned dynamically by Aspire DCP or bound via configuration:

Service Name	Host Access URL	Functional Purpose
Aspire Dashboard	See terminal output URL	Unified OpenTelemetry dashboard: container health, live logs, distributed tracing, and metrics (OTLP 16175, Resource Service 17037)
YARP Gateway	`http://localhost:6880`	Reverse proxy and unified routing gateway
API Host	`http://localhost:6881` `https://localhost:6883`	Core Minimal API host; OpenAPI documentation at `/scalar/v1`
Web Admin Console	`http://localhost:5860`	React 19 + Vite local development hot-reload server
SQL Server 2022	`localhost,14333`	Pinned port for AppHost persistence; user `sa`, password passed via env vars, non-conflicting with Compose port 1433
Redis 7	Dynamic DCP port / default `6379`	Injected via Aspire connection strings; fixed at `localhost:6379` under Docker Compose
MinIO Object Storage	Dynamic DCP port / default `9000`	S3-compatible object storage API and web management console

Development Execution & Volume Persistence Patterns

1. Team Daily Workflow: Persistent Volume Mode (Recommended)

During regular development iterations, database state should persist across machine restarts to prevent repetitive database seeding:

# Export persistence environment variables and launch the orchestration
ASPIRE_PERSIST_SQLSERVER=true ASPIRE_PERSIST_MINIO=true dotnet run --project src/Hosts/BitzOrcas.AppHost

2. Database Schema Reset: Zero-Friction Re-initialization

When local testing produces corrupted test data or upstream migrations introduce breaking schema changes, trigger a clean wipe and re-seed:

# Force full schema wipe and re-run seed data contributors
BITZORCAS_ASPIRE_RESET_SCHEMA=true dotnet run --project src/Hosts/BitzOrcas.AppHost

Troubleshooting & Common Local Failures

Port Conflicts (14333, 6880, or 6881 already in use):
- Check if an orphaned Docker container or local physical SQL Server / IIS process is already running;
- Run lsof -i :14333 or lsof -i :6880 on macOS/Linux to identify and terminate conflicting PIDs.
Docker Desktop Resource Starvation:
- The SQL Server 2022 container requires at least 2 GB of memory allocated to Docker. We recommend allocating 4 GB or more in Docker Desktop settings;
- On Apple Silicon (M1/M2/M3/M4) Macs, ensure Rosetta 2 emulation is enabled in Docker Desktop settings to ensure fast emulation for linux/amd64 images.