Common Environments

Core Principle

The application code must not change between environments.

Only the following are allowed to vary:

• Service addresses (localhost vs Docker DNS vs AWS endpoints)
• Configuration source (JSON, code, Parameter Store)
• Level of mocking (WireMock vs real services)

If behavior changes beyond that, the environment boundary is broken.

Development Environment

Development Intent

Run the API locally as a process with a debugger attached, while dependencies run in Docker.

This is the lowest-friction environment and the fastest feedback loop.

Development Characteristics

• API runs outside Docker
• Dependencies run inside Docker
• All services are addressed via localhost
• WireMock is used for external HTTP dependencies

Configuration

ASPNETCORE_ENVIRONMENT: Development

{
  "Database": {
    "ConnectionStrings": {
      "XXTemplateXXPostgreSql": "Host=localhost;Port=5432;..."
    }
  },
  "Cognito": {
    "Domain": "http://localhost:8080",
    "RedirectUri": "http://localhost:5000/auth/oauth/callback"
  },
  "Localstack": {
    "ServiceUrl": "http://localhost:4566/"
  }
}

How to Run Development Environment

1. Start dependencies only:

   pnpm docker:up
   

2. Run API locally:

   dotnet run
   

3. Run frontend:

   pnpm dev
   

LocalDevelopment Environment

LocalDevelopment Intent

Run the entire stack inside Docker to surface issues related to networking, DNS, and container boundaries.

This is the first environment that behaves like production.

LocalDevelopment Characteristics

• API runs in Docker
• Dependencies run in Docker
• All communication uses Docker internal DNS
• No service is reachable via localhost internally

LocalDevelopment Configuration

ASPNETCORE_ENVIRONMENT: LocalDevelopment

{
  "Database": {
    "ConnectionStrings": {
      "XXTemplateXXPostgreSql": "Host=postgre-database;Port=5432;..."
    }
  },
  "Cognito": {
    "Domain": "http://wiremock:8080",
    "RedirectUri": "http://xxtemplatexx-api:80/auth/oauth/callback"
  },
  "Localstack": {
    "ServiceUrl": "http://localstack:4566/"
  }
}

Docker Internal DNS

How to Run

pnpm docker:up

Test Environment

Test Intent

Execute isolated, reproducible integration tests without relying on shared infrastructure.

Test Characteristics

• API hosted in-memory
• All dependencies started via Testcontainers
• Configuration is defined programmatically
• No appsettings.*.json files are used

Pattern

public class ApiServicesFactory 
    : WebApplicationFactory<IMinimalApiMarker>, IAsyncLifetime
{
    private readonly PostgreSqlContainer _postgresContainer;
    private readonly LocalStackContainer _localStackContainer;
    private readonly WireMockContainer _wireMockContainer;

    public async Task InitializeAsync()
    {
        await _postgresContainer.StartAsync();
        await _localStackContainer.StartAsync();
        await _wireMockContainer.StartAsync();
    }
}

Guarantees

• Fresh state per test run
• Identical behavior locally and in CI
• No external dependencies
• Same WireMock mappings as other environments

Run with:

dotnet test

Production Environment

Production Intent

Run the system in AWS using real managed services with secure configuration.

Production Characteristics

• API runs in AWS Lambda or ECS
• No mocks
• Secrets are never stored in the repository
• Configuration is split by sensitivity

Configuration Loading

builder.Host.ConfigureParameterStore<IMinimalApiMarker>();

Parameter Store (Sensitive)

• OAuth client secrets
• JWT signing keys
• Database credentials
• Cognito configuration

appsettings.json (Non-Sensitive)

• Queue names
• Bucket names
• Log levels
• AWS region
• Feature flags

WireMock Contract

WireMock is a shared dependency across environments, not a test-only tool.

Used in:

• Development
• LocalDevelopment
• Test

Same mappings. Same behavior. Same OAuth contract.

Location:

scripts/development/wiremock/
├── mappings/
└── __files/

This guarantees parity between local debugging, Docker E2E, and tests.

Configuration Hierarchy

appsettings.json
├── appsettings.Development.json
├── appsettings.LocalDevelopment.json
├── appsettings.Production.json
└── AWS Parameter Store (Production only)

Priority (highest wins):

1. Environment variables
2. AWS Parameter Store
3. appsettings.{Environment}.json
4. appsettings.json

Summary Matrix

Final Rule

If an issue appears in LocalDevelopment or Test but not in Development, the code was relying on an invalid assumption.

That is the point of having multiple environments.