In daily development and multi-module integration, managing disjointed startup scripts across distributed services is notoriously exhausting: crashed database containers, out-of-sync cache states, and misaligned gateway port bindings frequently disrupt developer velocity.

BitzOrcas.Modern integrates deeply with .NET Aspire AppHost. Leveraging Aspire’s modern orchestration engine, engineers can spin up the complete infrastructure stack—SQL Server, Redis, RabbitMQ, MinIO—alongside the API Host, YARP Gateway, and Web frontend with a single command, accompanied by a centralized OpenTelemetry observability dashboard.

Development Orchestration Topology

Step 1: Preferred Mode — .NET Aspire AppHost Orchestration

Run the AppHost startup command from the repository root to evaluate service dependencies and launch the full stack:

# Start the Aspire AppHost
dotnet run --project src/Hosts/BitzOrcas.AppHost

Upon startup, the console prints the Aspire Dashboard URL (typically http://localhost:15000 or a high-range dynamic port). Open this URL in your browser to inspect system telemetry:

Resources: Monitor health states, memory allocations, and environment variables across all running processes and containers.
Structured Traces: Inspect microsecond-resolution Gantt charts tracking each incoming HTTP request as it traverses the 10-tier application pipeline and relational database queries.
Console & Structured Logs: Query aggregated logs across all components filtered instantly by TraceId.

Step 2: Development Data Lifecycle (Persistence vs. Reset)

Frequent restarts should not wipe away seeded datasets and test entities. AppHost provides precise volume persistence and seeding toggles:

1. Team Daily Feature Development: Enable Volume Persistence (Default Recommendation)

Preserve database records and uploaded objects across restart cycles:

# Persist relational database and object storage only (clearing transient Redis or RabbitMQ state)
ASPIRE_PERSIST_SQLSERVER=true ASPIRE_PERSIST_MINIO=true dotnet run --project src/Hosts/BitzOrcas.AppHost

# Or persist all infrastructure volumes
ASPIRE_PERSIST_VOLUMES=true dotnet run --project src/Hosts/BitzOrcas.AppHost

2. Destructive Refactoring Recovery: Controlled Reset and Re-seeding (Reset Schema)

When aggregate models undergo breaking changes requiring clean database rebuilds:

# Permitted strictly in Development environments; aborts automatically in Production/Staging
BITZORCAS_ASPIRE_RESET_SCHEMA=true BITZORCAS_ASPIRE_SEED_DEMO=true dotnet run --project src/Hosts/BitzOrcas.AppHost

Step 3: Zero-Downtime Maintenance & Instant Component Restarts

During feature development, modifying backend API code does not require stopping the entire Aspire container network:

Dashboard Hot Restart: Locate bitzorcas-api inside the Aspire Dashboard and click Restart. Relational databases and Redis instances remain online; the API host restarts in under a second.
Re-apply System Seeds (—seed-only): When permissions, menus, or seed dictionaries are modified in source code, re-apply them without restarting running hosts:
Re-apply system seed definitions
```
dotnet run --project src/Hosts/BitzOrcas.Api -- --seed-only
```

Step 4: Alternative Mode — Standalone Shell Mode (Non-Aspire)

In constrained development virtual machines or lightweight CI pipelines, execute standard Docker Compose and dotnet run:

# 1. Start background infrastructure containers
docker compose up -d

# 2. Launch API Host (Listening on http://localhost:6881 and https://localhost:6883)
dotnet run --project src/Hosts/BitzOrcas.Api

Step 5: Executing Your First Authentication Request

Once the service reports healthy, open the interactive Scalar API documentation in your browser: http://localhost:6881/scalar/v1.

Execute the following sequential curl commands in terminal to verify health probes and authentication:

1. Health Probe and Public Encryption Key Retrieval

# 1. Inspect live health probe (returns HTTP 200 OK)
curl -i http://localhost:6881/health/live

# 2. Fetch RSA-OAEP public key and keyId
curl -i http://localhost:6881/api/auth/cipher-key

Sample public key response:

{
  "keyId": "cipher-key-20260923",
  "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...\n-----END PUBLIC KEY-----\n",
  "serverTime": 1790188800
}

The authentication endpoint POST /api/auth/login rejects plaintext passwords. In development environments, submit credentials via the Web Admin monorepo (http://localhost:6800) or the Scalar documentation playground, which handle RSA-OAEP encryption transparently.

Using the default development super administrator:

Username: admin
Development Password: Admin@2026 (The frontend packages payload as nonce|timestamp|Admin@2026 before encrypting with OAEP-SHA256).

3. Verify Identity Using the Issued JWT

Upon successful login, extract accessToken and invoke the identity introspection endpoint:

curl http://localhost:6881/api/auth/me \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN_HERE>"

The response details tenant context, identity claims, and active permission policies:

{
  "userId": "1000000000000001",
  "tenantId": "1000001",
  "userName": "admin",
  "displayName": "System Super Admin",
  "roles": ["SuperAdmin"],
  "permissions": [
    "Identity.User.Search",
    "Identity.User.Create",
    "Authorization.Role.Grant",
    "Authorization.TenantDataScope",
    "Authorization.RootCrossTenant"
  ]
}

You have now completed the entire operational onboarding cycle from orchestration and persistence to secure authentication. Proceed to Pre-Seeded Demo Accounts and the Password Injection Contract or explore hands-on tutorials to construct your first vertical slice.