Skip to main content

​
Minimal setup

For most services — SSM, SQS, SNS, S3, DynamoDB, API Gateway, Cognito, KMS, Kinesis, Secrets Manager, CloudFormation, Step Functions, IAM, STS, EventBridge, and CloudWatch — a single port is all you need: 
services:
  floci:
    image: hectorvent/floci:latest
    ports:
      - "4566:4566"
    volumes:
      - ./data:/app/data
All AWS API calls go to http://localhost:4566. Credentials can be anything.

​
Full setup (with Lambda, ElastiCache, and RDS)

Lambda, ElastiCache, and RDS work by spawning real Docker containers. Floci needs access to the Docker socket to manage those containers, and their ports must be exposed to the host so your application can connect directly. 
services:
  floci:
    image: hectorvent/floci:latest
    ports:
      - "4566:4566"              # All AWS API calls
      - "6379-6399:6379-6399"   # ElastiCache / Valkey proxy ports
      - "7001-7099:7001-7099"   # RDS / PostgreSQL + MySQL proxy ports
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock  # Required for Lambda, ElastiCache, RDS
      - ./data:/app/data
      - ./init/start.d:/etc/floci/init/start.d:ro
      - ./init/stop.d:/etc/floci/init/stop.d:ro
    environment:
      FLOCI_SERVICES_DOCKER_NETWORK: my-project_default
      FLOCI_STORAGE_MODE: hybrid
      FLOCI_STORAGE_PERSISTENT_PATH: /app/data

​
Port reference

Port / RangeProtocolPurpose
4566HTTPAll AWS API calls (every service)
6379–6399TCPElastiCache proxy — one port per replication group
7001–7099TCPRDS proxy — one port per DB instance
When Floci creates an ElastiCache replication group or RDS instance, it starts the backing Docker container and assigns the next available port in the respective range. The assigned port is returned in the API response (PrimaryEndpoint.Port for ElastiCache, Endpoint.Port for RDS).

​
Multi-container setup

When your application runs in a separate container from Floci, response URLs that contain localhost (such as SQS QueueUrl) won’t resolve correctly inside your app container.
If you run your application in a separate container without setting FLOCI_HOSTNAME, SQS and other services will return URLs containing localhost:4566. Your app container will try to connect to its own loopback interface instead of the Floci container, causing connection failures.
1

Add Floci to your Compose file

Define the Floci service with the FLOCI_HOSTNAME environment variable set to its service name. This tells Floci to use that hostname when building response URLs.
services:
  floci:
    image: hectorvent/floci:latest
    ports:
      - "4566:4566"
    environment:
      FLOCI_HOSTNAME: floci   # Floci uses http://floci:4566/... in all response URLs
2

Configure your application container

Point your app’s AWS SDK at the Floci container using its service name as the hostname, and declare the dependency so Floci starts first.
  my-app:
    build: .
    environment:
      AWS_ENDPOINT_URL: http://floci:4566
      AWS_DEFAULT_REGION: us-east-1
      AWS_ACCESS_KEY_ID: test
      AWS_SECRET_ACCESS_KEY: test
    depends_on:
      - floci
3

Attach spawned containers to the same network

Lambda, ElastiCache, and RDS spawn additional Docker containers. Set FLOCI_SERVICES_DOCKER_NETWORK to the name of the network your Compose project creates (typically <project-name>_default) so those containers can communicate with your app.
  floci:
    image: hectorvent/floci:latest
    environment:
      FLOCI_HOSTNAME: floci
      FLOCI_SERVICES_DOCKER_NETWORK: my-project_default
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
4

Start the stack

docker compose up
Your application can now call http://floci:4566 and all returned URLs (SQS QueueUrl, S3 pre-signed URLs, SNS endpoints) will use floci as the hostname, resolving correctly from any container in the network.

​
Environment variable reference

VariableDefaultDescription
FLOCI_DEFAULT_REGIONus-east-1AWS region in ARNs
FLOCI_DEFAULT_ACCOUNT_ID000000000000AWS account ID in ARNs
FLOCI_HOSTNAME(unset)Override hostname in response URLs
FLOCI_STORAGE_MODEmemoryGlobal storage mode (memory, persistent, hybrid, wal)
FLOCI_STORAGE_PERSISTENT_PATH./dataDirectory for persistent storage
FLOCI_SERVICES_LAMBDA_DOCKER_HOSTunix:///var/run/docker.sockDocker host for Lambda containers
FLOCI_SERVICES_LAMBDA_EPHEMERALfalseRemove Lambda containers after each invocation
FLOCI_SERVICES_LAMBDA_DEFAULT_MEMORY_MB128Default Lambda memory allocation
FLOCI_SERVICES_LAMBDA_DEFAULT_TIMEOUT_SECONDS3Default Lambda timeout
FLOCI_SERVICES_LAMBDA_CODE_PATH./data/lambda-codeWhere Lambda ZIPs are stored
FLOCI_SERVICES_ELASTICACHE_PROXY_BASE_PORT6379First ElastiCache proxy port
FLOCI_SERVICES_ELASTICACHE_PROXY_MAX_PORT6399Last ElastiCache proxy port
FLOCI_SERVICES_ELASTICACHE_DEFAULT_IMAGEvalkey/valkey:8Default Valkey/Redis Docker image
FLOCI_SERVICES_RDS_PROXY_BASE_PORT7001First RDS proxy port
FLOCI_SERVICES_RDS_PROXY_MAX_PORT7099Last RDS proxy port
FLOCI_SERVICES_RDS_DEFAULT_POSTGRES_IMAGEpostgres:16-alpineDefault PostgreSQL image
FLOCI_SERVICES_RDS_DEFAULT_MYSQL_IMAGEmysql:8.0Default MySQL image
FLOCI_SERVICES_RDS_DEFAULT_MARIADB_IMAGEmariadb:11Default MariaDB image
FLOCI_SERVICES_DOCKER_NETWORK(none)Docker network for spawned containers
FLOCI_AUTH_VALIDATE_SIGNATURESfalseVerify AWS request signatures

Build docs developers (and LLMs) love

Get started for freeTalk to us