Docker Deployment

Simfra is distributed as a single container image based on scratch (no shell, no OS). The image includes the Simfra binary, the Docker CLI, Terraform, and CA certificates.

Image: ghcr.io/simfra-dev/simfra:latest

Basic Usage

Start Simfra with a bootstrapped default account:

docker run -d \
  --name simfra \
  -p 4599:4599 \
  -e SIMFRA_BOOTSTRAP=standard \
  ghcr.io/simfra-dev/simfra:latest

This gives you a fully functional AWS emulator on port 4599 with a default VPC, KMS keys, and IAM service-linked roles. All state is ephemeral.

With Docker-Backed Services

To enable real compute and database containers (Lambda, EC2, RDS, ELBv2, EKS, etc.), mount the Docker socket:

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

Simfra creates and manages sibling containers on the host Docker daemon. Service containers are automatically cleaned up on shutdown.

With Persistence

To survive restarts, mount a volume for SIMFRA_DATA_DIR:

docker run -d \
  --name simfra \
  -p 4599:4599 \
  -v simfra-data:/data \
  -e SIMFRA_DATA_DIR=/data \
  -e SIMFRA_BOOTSTRAP=standard \
  ghcr.io/simfra-dev/simfra:latest

Resource metadata is stored in SQLite at /data/simfra.db. S3 objects are stored under /data/s3/. On restart, all persisted state is reloaded into memory before the server starts accepting requests.

Docker Compose

A full-featured setup with Docker-backed services, persistence, and custom credentials:

services:
  simfra:
    image: ghcr.io/simfra-dev/simfra:latest
    ports:
      - "4599:4599"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - simfra-data:/data
    environment:
      SIMFRA_BOOTSTRAP: standard
      SIMFRA_DOCKER: "true"
      SIMFRA_DATA_DIR: /data
      SIMFRA_LOG_LEVEL: info
      SIMFRA_DEFAULT_ACCOUNT_ID: "123456789012"
      SIMFRA_ROOT_ACCESS_KEY_ID: AKIAEXAMPLE123456789
      SIMFRA_ROOT_SECRET_ACCESS_KEY: secretkey/example/1234567890abcdef
    healthcheck:
      test: ["/usr/local/bin/simfra", "health"]
      interval: 10s
      timeout: 3s
      start_period: 5s
      retries: 3
    restart: unless-stopped

volumes:
  simfra-data:

Health Check

The container includes a built-in health check command:

/usr/local/bin/simfra health

This hits the /_simfra/health endpoint on localhost and exits with code 0 on success, 1 on failure. The Dockerfile configures this as the default HEALTHCHECK. The health endpoint returns 200 only after all persisted state has been loaded and bootstrap has completed.

Port Exposure

Simfra multiplexes all AWS services on a single port (default 4599). When Docker-backed services are enabled, additional ports may be published for direct-access services (database connections, load balancer traffic, etc.). See Port Ranges for details.

To expose all service port ranges to the host:

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

Environment Variables

See Environment Variables for the complete reference. The most relevant for Docker deployment:

Variable	Purpose
SIMFRA_PORT	Change the listen port (default 4599)
SIMFRA_BOOTSTRAP	Initialize default account resources
SIMFRA_DOCKER	Enable Docker-backed services
SIMFRA_DATA_DIR	Enable persistent storage
SIMFRA_LOG_LEVEL	Control log verbosity
SIMFRA_DOCKER_CLEANUP_ON_START	Clean stale containers on startup (default true)
SIMFRA_DOCKER_CLEANUP_ON_SHUTDOWN	Clean containers on shutdown (default true)