Docker-Backed Services
Setting SIMFRA_DOCKER=true enables Docker-backed services. Instead of simulating compute and database operations in-process, Simfra creates real Docker containers that run actual database engines, Lambda runtimes, web servers, and more.
Requirements
- Docker daemon accessible via
/var/run/docker.sock - Sufficient disk space for container images
- 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
Services with Docker Backends
When Docker is enabled, the following services run real containers:
| Service | What Runs | Default Image |
|---|---|---|
| Lambda | Function code in AWS-compatible runtime containers | public.ecr.aws/lambda/* |
| EC2 | Instances as Docker containers with SSH, IMDS, and user data | amazonlinux:2023 |
| RDS | MySQL, PostgreSQL, or MariaDB database servers | mysql:8.0, postgres:16, mariadb:10.11 |
| RDS Proxy | Connection pooling proxy containers | Simfra sidecar image |
| ElastiCache | Redis, Valkey, or Memcached servers | redis:7, valkey/valkey:8, memcached:1.6 |
| ELBv2 | Load balancer containers with real traffic routing | Simfra sidecar image |
| EKS | Kubernetes control plane (k3s) with real kubectl access | k3s image |
| Route53 | DNS server containers resolving hosted zones | Simfra sidecar image |
| CloudFront | CDN containers proxying to origins | Simfra sidecar image |
| EFS | NFS server containers for shared filesystems | Simfra sidecar image |
| ECS | Task containers running on Docker | Application images |
| Amazon MQ | ActiveMQ or RabbitMQ message brokers | apache/activemq-classic:5.18.6, rabbitmq:3.13-management |
| MSK | Apache Kafka brokers (KRaft mode) | apache/kafka:3.9.0 |
| OpenSearch | OpenSearch domain containers | opensearchproject/opensearch:2.19.1 |
| Redshift | PostgreSQL-compatible query engine | postgres:16 |
| DSQL | PostgreSQL-compatible distributed SQL | postgres:16 |
| CodeCommit | Git server with SSH/HTTPS access | Simfra sidecar image |
| CodeBuild | Build containers executing buildspec.yml | Application images |
| Directory Service | Samba AD domain controllers | Simfra sidecar image |
| Cognito Hosted UI | OAuth2/OIDC login pages | Simfra sidecar image |
| SES v2 | SMTP server for email sending | Simfra sidecar image |
| Bedrock Runtime | LLM inference via Ollama or stable-diffusion.cpp | ollama/ollama:latest |
| API Gateway | HTTP proxy containers for API routes | Simfra sidecar image |
| Glue | Spark/Python job containers | Application images |
Without Docker
When SIMFRA_DOCKER=false (the default), all services operate in API-only mode. API calls succeed and return correct responses, but there are no running containers. For example:
- RDS CreateDBInstance returns a valid endpoint, but nothing listens on it
- Lambda CreateFunction succeeds, but Invoke returns a simulated response
- EC2 RunInstances creates instance records, but no compute runs
This is sufficient for testing infrastructure-as-code, API integration, and IAM policies.
Image Overrides
Every Docker-backed service has an environment variable to override its container image. This is essential for:
- Air-gapped environments: Point to a private registry with pre-pulled images
- Version pinning: Lock to a specific database or runtime version
- Custom images: Use modified images with additional tools or configuration
See Environment Variables for the complete list.
Registry Override (Recommended)
Set SIMFRA_DOCKER_IMAGE_REGISTRY to redirect all Docker images to a private or internal registry. This is the simplest way to use Simfra in air-gapped or corporate environments - you do not need to override each service image individually:
export SIMFRA_DOCKER_IMAGE_REGISTRY=registry.internal.example.com/simfra
This prefixes every image Simfra pulls - sidecar containers (load balancer, DNS, CDN, browser, CloudShell), database engines (MySQL, PostgreSQL, Redis), compute runtimes (Lambda, EC2), and infrastructure containers (EKS/Kind, Kafka, ActiveMQ).
Optionally pin a specific tag across all sidecar images:
export SIMFRA_DOCKER_IMAGE_TAG=v1.5.0
Per-service image overrides (e.g., SIMFRA_RDS_IMAGE_POSTGRES) take precedence over the global registry when set. Use them only when you need a different image for a specific service.
VPC Network Isolation
When Docker is enabled, SIMFRA_VPC_ISOLATION defaults to true. This means:
- Each VPC gets its own Docker bridge network
- Private resources (internal load balancers, private RDS instances, private subnets) are only attached to their VPC network - no host ports are published
- Public resources (internet-facing load balancers, publicly accessible RDS instances) get both VPC network attachment and host port publishing
- The Docker host is treated as "the public internet"
To disable VPC isolation and publish all ports to the host:
export SIMFRA_VPC_ISOLATION=false
Container Lifecycle
Simfra manages Docker containers automatically:
- Creation: Containers are created when the corresponding AWS resource is created (e.g.,
CreateDBInstance,RunInstances) - Cleanup on start:
SIMFRA_DOCKER_CLEANUP_ON_START=true(default) removes stale containers from previous runs - Cleanup on shutdown:
SIMFRA_DOCKER_CLEANUP_ON_SHUTDOWN=true(default) removes all Simfra-managed containers on graceful shutdown - Reconciliation: On restart with persistence, containers are recreated from persisted resource metadata
All Simfra-managed containers are labeled for identification and cleanup.
Container Communication
Containers communicate with Simfra using a pull/webhook model:
- Containers poll Simfra for configuration updates via
/_internal/container/config - Containers push status/health back via
/_internal/container/status - No config files are bind-mounted into containers
- The
SIMFRA_HOSTNAME(defaultsimfra.local) is resolved by the DNS container
This design ensures containers work identically whether Simfra runs on the host or inside Docker itself.