Local Dev & CI/CD

The last lesson, and arguably the most important. Everything in the previous 14 lessons is moot if you can’t iterate quickly, test reliably, and ship safely. Three pieces — local emulator, CI-friendly tests, infra-as-code — and you’re set.

Local development with the emulator

Start the emulator in Docker:

docker run --publish 8081:8081 \
  --publish 10250-10255:10250-10255 \
  mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator-vnext-preview

Point your SDK at it:

var client = new CosmosClient(
  "https://localhost:8081",
  // Well-known emulator key — same in everyone's repo, not a secret
  "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==",
  new CosmosClientOptions {
    HttpClientFactory = () => new HttpClient(new HttpClientHandler {
      ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator
    })
  });

(The TLS bypass is only because the emulator uses a self-signed cert. Don’t carry that into prod code.)

The vNext emulator starts in ~5 seconds vs. the legacy one’s ~30. SQL API only, but that’s all most apps need. Run it as a service in your docker-compose.yml alongside your app and you have offline development.

CI integration tests

GitHub Actions example — runs the emulator as a service container:

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      cosmos:
        image: mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator-vnext-preview
        ports: ['8081:8081']
        options: --health-cmd "curl -kf https://localhost:8081/" --health-interval 5s --health-retries 30
    steps:
      - uses: actions/checkout@v4
      - run: dotnet test --filter Category=Integration
        env:
          COSMOS_ENDPOINT: https://localhost:8081
          COSMOS_KEY: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==

Each test creates and drops its own database. Parallel tests don’t interfere. No Azure spend, no flaky shared state.

Infrastructure as code

For the account, container, and policy — pick Bicep (Azure-native) or Terraform (multi-cloud). The Bicep equivalent of “one Cosmos account with one database and one container”:

resource account 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = {
  name: 'cosmos-${appName}-${env}'
  location: location
  kind: 'GlobalDocumentDB'
  properties: {
    consistencyPolicy: { defaultConsistencyLevel: 'Session' }
    locations: [{ locationName: location, failoverPriority: 0 }]
    capabilities: [{ name: 'EnableServerless' }]
    disableLocalAuth: true
  }
}

resource db 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15' = {
  parent: account
  name: 'app'
  properties: { resource: { id: 'app' } }
}

resource orders 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers@2024-05-15' = {
  parent: db
  name: 'orders'
  properties: {
    resource: {
      id: 'orders'
      partitionKey: { paths: ['/userId'], kind: 'Hash' }
      indexingPolicy: {
        indexingMode: 'consistent'
        includedPaths: [{ path: '/*' }]
        excludedPaths: [{ path: '/payload/*' }, { path: '/_etag/?' }]
      }
    }
  }
}

This is a complete, deployable file. Check it in. Run it in CD. Production Cosmos is now reproducible.

Multi-environment topology

Common pattern — three environments, one repo:

Same Bicep template, parameterized. Deploy via your CD pipeline on merge to main (dev), tag (staging), manual approval (prod).

Migrations

Cosmos is schema-free, but your app has implicit schema. When you change the shape — adding a required field, splitting a doc — you need a migration strategy:

1. Dual-write — write the new shape to both old and new fields. Run for one release.
2. Backfill — Change Feed processor or one-off Spark job to populate new fields on old docs.
3. Read-side fallback — read code handles both shapes during transition.
4. Cleanup — once all docs are migrated, drop the old fields.

This is the same dance as SQL “expand-contract” migrations — version control both old and new shapes in your tests.

Wrapping the course

You’ve now seen the whole machine — APIs, partitioning, modeling, consistency, CRUD, querying, indexing, SDKs, RUs, monitoring, Change Feed, global distribution, security, vector search, and operations. The next step isn’t more theory — it’s building.

Pick a small app — a URL shortener, a personal CRM, a notes app. Model it Cosmos-first (lesson V03). Provision via Bicep (this lesson). Run it for a few weeks. Watch the metrics. Tune the index. That’s the loop, and it’s how Cosmos becomes muscle memory.