Application Development

Simfra is designed so that your application code works without modification. When SIMFRA_DOCKER=true, Lambda functions, ECS tasks, and EC2 instances run as real Docker containers - and Simfra automatically injects the configuration they need to route AWS SDK calls back to the emulator.

The Key Insight

Simfra injects AWS_ENDPOINT_URL into every Docker container it creates. All modern AWS SDKs (Go v2, Python boto3 1.28.57+, JavaScript v3, Java v2, .NET, Ruby) read this variable automatically and route API calls to Simfra instead of real AWS. Your application code does not need to know it is running against Simfra.

This means:

  • Lambda functions work as-is - no endpoint overrides, no conditionals, no test-only code paths
  • ECS tasks call AWS APIs normally - S3, DynamoDB, SQS, Secrets Manager all route to Simfra
  • EC2 instances with IAM instance profiles get credentials via IMDS, exactly like on real AWS

What Gets Injected

Each compute environment receives a different set of environment variables, matching how real AWS provisions credentials and configuration:

Environment AWS_ENDPOINT_URL Credentials Region
Lambda Injected Execution role via STS (temporary credentials) AWS_REGION + AWS_DEFAULT_REGION
ECS Injected Root credentials (static) AWS_DEFAULT_REGION
EC2 Not injected IMDS (instance profile) or static fallback AWS_REGION + AWS_DEFAULT_REGION
Host Set manually Set manually Set manually

EC2 instances use IMDS for credential discovery rather than AWS_ENDPOINT_URL, matching real AWS behavior. See Running EC2 Workloads for details.

Pages