Docker-Backed Services

Simfra operates in two modes. By default, all services run as in-memory API emulations - API calls succeed and return correct responses, but no real compute or database processes run behind them.

Setting SIMFRA_DOCKER=true changes that. Services that benefit from real execution environments create Docker containers running actual software:

  • Lambda executes your function code in AWS-compatible runtime containers.
  • RDS runs real MySQL, PostgreSQL, and MariaDB database servers you can connect to with standard clients.
  • ElastiCache runs real Redis, Valkey, and Memcached servers.
  • EKS creates real Kubernetes clusters (via Kind) with working kubectl access.
  • ECR operates a full Docker Registry V2, so you can push and pull container images.
  • Bedrock runs LLM inference via Ollama, supporting the Converse and InvokeModel APIs.

Other Docker-backed services include EC2 (instances as containers), ECS (task containers), ELBv2 (real load balancers), RDS Proxy, CloudFront, Route53 DNS, Amazon MQ, MSK (Kafka), OpenSearch, Redshift, CodeBuild, CodeCommit, EFS, Directory Service, Cognito Hosted UI, SES (SMTP), and Glue.

Prerequisites

  • Docker daemon accessible via /var/run/docker.sock
  • Sufficient disk space for container images (varies by which services you use)
  • Port ranges available on the host (see Port Ranges)

Enabling Docker Mode

export SIMFRA_DOCKER=true
simfra

Or with Docker:

docker run -d \
  -p 4599:4599 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e SIMFRA_DOCKER=true \
  -e SIMFRA_BOOTSTRAP=standard \
  ghcr.io/simfra-dev/simfra:latest

How Containers Work

Simfra manages the full container lifecycle automatically. Containers are created when you create the corresponding AWS resource (e.g., CreateDBInstance starts a PostgreSQL container), and removed when you delete the resource.

All containers use a pull/webhook communication model:

  • Containers poll Simfra for configuration updates via /_internal/container/config.
  • Containers push health and status back via /_internal/container/status.
  • No config files are bind-mounted into containers.

VPC Network Isolation

When Docker is enabled, SIMFRA_VPC_ISOLATION defaults to true. Each VPC gets its own Docker bridge network:

  • Private resources (internal LBs, private RDS instances, ElastiCache clusters) are only attached to their VPC network. No host ports are published. They are reachable from other containers on the same VPC network, or via port forwarding.
  • Public resources (internet-facing LBs, publicly accessible RDS) get both VPC network attachment and host port publishing.

The Docker host is treated as "the public internet."

Port Forwarding to Private Resources

Private resources that do not publish host ports can be accessed via port forwarding:

curl -X POST http://localhost:4599/_simfra/port-forwards \
  -d '{"targetArn":"arn:aws:elasticache:us-east-1:000000000000:cluster:my-cache","targetPort":6379}'

This creates a socat proxy container that publishes a host port and tunnels traffic to the private container's VPC network.

DNS Resolution

Simfra runs a DNS container per account that resolves service endpoint names (RDS endpoints, ElastiCache endpoints, EKS API server URLs) to the correct container IPs. Lambda functions, ECS tasks, and EKS pods use this DNS automatically - your application code can connect to RDS or ElastiCache endpoints by name without any special configuration.

Guides