Docker Issues

Docker-backed services (Lambda, RDS, ECS, EC2, ELBv2, ElastiCache, CloudFront, etc.) require SIMFRA_DOCKER=true and access to the Docker daemon.

Docker socket not mounted

Symptom: SIMFRA_DOCKER=true is set but Docker operations fail with "cannot connect to Docker daemon" or similar errors.

Solutions:

When running Simfra in Docker, mount the Docker socket:

docker run -v /var/run/docker.sock:/var/run/docker.sock \
  -e SIMFRA_DOCKER=true \
  ghcr.io/simfra-dev/simfra:latest

On macOS with Docker Desktop, the socket is at /var/run/docker.sock by default. Verify it exists:
```
ls -la /var/run/docker.sock
```
On Linux, ensure the user running Simfra has permission to access the Docker socket (is in the docker group or running as root).

Image pull failures

Symptom: Container creation fails with image pull errors.

Solutions:

Network access - Verify the Docker daemon can reach the image registry. Test with:
```
docker pull amazonlinux:2023
```
Private registry - If using a private registry, set SIMFRA_DOCKER_IMAGE_REGISTRY to the registry prefix:
```
export SIMFRA_DOCKER_IMAGE_REGISTRY=ghcr.io/myorg
```
Lambda images - Lambda runtime images are pulled from public.ecr.aws/lambda by default. Override with SIMFRA_LAMBDA_IMAGE_REGISTRY if your environment cannot reach ECR Public.
Image tag - Override the default image tag for Simfra service containers with SIMFRA_DOCKER_IMAGE_TAG.
Service-specific images - Individual service images can be overridden:
- SIMFRA_RDS_IMAGE_MYSQL, SIMFRA_RDS_IMAGE_POSTGRES, SIMFRA_RDS_IMAGE_MARIADB
- SIMFRA_ELASTICACHE_IMAGE_REDIS, SIMFRA_ELASTICACHE_IMAGE_VALKEY, SIMFRA_ELASTICACHE_IMAGE_MEMCACHED
- SIMFRA_EC2_IMAGE_AMAZONLINUX2023, SIMFRA_EC2_IMAGE_UBUNTU
- SIMFRA_BEDROCK_OLLAMA_IMAGE

Container startup failures

Symptom: Docker containers are created but fail to start or crash immediately.

Solutions:

Check container logs:

# Via admin API
curl http://localhost:4599/_simfra/docker/containers

# Get logs for a specific container
curl http://localhost:4599/_simfra/docker/containers/{id}/logs

Check Simfra logs - Set SIMFRA_LOG_LEVEL=debug for detailed container lifecycle logging.

Verify the image works standalone:

docker run --rm postgres:16 postgres --version

Check resource limits - Docker may have insufficient memory or CPU configured. On Docker Desktop, check Settings > Resources.

Port conflicts

Symptom: Container creation fails with "port is already allocated" or "bind: address already in use".

Each Docker-backed service allocates host ports from a configurable range. Conflicts occur when multiple services or external applications use the same ports.

Solutions:

Customize port ranges - Move conflicting services to different ranges:
```
export SIMFRA_RDS_PORT_RANGE=20400-20499
export SIMFRA_ELBV2_PORT_RANGE=20200-20299
```
See Port Ranges for the full list of defaults.
Check what is using the port:
```
lsof -i :10400
```
Widen the range if you need more concurrent containers:
```
export SIMFRA_RDS_PORT_RANGE=10400-10599
```
Use random ports by setting the range to 0:
```
export SIMFRA_RDS_PORT_RANGE=0
```
Note: random ports are harder to predict and may complicate client configuration.

VPC network issues

Symptom: Containers cannot communicate with each other or with Simfra. Private resources are unreachable.

Solutions:

Check Docker network exists - Simfra creates Docker bridge networks named simfra-vpc-{accountId}-{vpcId} for VPC isolation. List them with:
```
curl http://localhost:4599/_simfra/docker/networks
```
Verify container connectivity - Containers on the same VPC network should be able to reach each other. Check with:
```
docker exec <container_id> ping <target_ip>
```
VPC isolation mode - When SIMFRA_VPC_ISOLATION=true (the default when Docker is enabled), private containers do not publish ports to the host. Use port forwarding to access them:
```
curl -X POST http://localhost:4599/_simfra/port-forwards \
  -d '{"targetArn": "arn:aws:rds:us-east-1:000000000000:db:mydb"}'
```
DNS resolution - Containers use Simfra's DNS server for name resolution. If DNS is not working, check the DNS container is running:
```
curl http://localhost:4599/_simfra/dns/000000000000
```

Containers not starting

Symptom: Simfra acknowledges resource creation but the backing container never starts.

Solutions:

Ensure Docker has enough resources - Check available disk space, memory, and CPU. Docker Desktop on macOS defaults to limited resources.
Check disk space - Docker images and containers consume disk. Clean unused resources:
```
docker system prune
```
Cleanup stale containers - Previous Simfra sessions may have left containers. Clean up via the admin API:
```
curl -X POST http://localhost:4599/_simfra/docker/cleanup
```
Or set SIMFRA_DOCKER_CLEANUP_ON_START=true (the default) to clean up automatically on startup.
Docker daemon health - Verify Docker is responsive:
```
docker info
```