Configuration overview

Floci is configured through three equivalent mechanisms. You can mix them freely — environment variables always take precedence over file-based configuration.

Approach	How it works
Environment variables	Set `FLOCI_*` vars in your shell, CI, or docker-compose
`application.yml` mount	Mount a YAML file into the container at `/app/config/application.yml`
docker-compose `environment:` block	Set `FLOCI_*` keys inline in your Compose service definition

Every application.yml key maps to an environment variable with the FLOCI_ prefix. Replace dots and dashes with underscores and uppercase everything. For example, floci.default-region becomes FLOCI_DEFAULT_REGION.

Core settings

body.base-url

string

default:"http://localhost:4566"

Base URL used to build callback and response URLs — for example, SNS subscription endpoints and SQS QueueUrl values. When your application runs in a separate container, set FLOCI_HOSTNAME instead of changing this directly.

body.default-region

string

default:"us-east-1"

AWS region reported in ARNs and API responses. Any valid AWS region string is accepted.

body.default-account-id

string

default:"000000000000"

AWS account ID used in ARNs. Any 12-digit string works for local development.

body.storage.mode

string

default:"memory"

Global storage backend. Accepted values: memory, persistent, hybrid, wal. See Storage for a full comparison.

body.max-request-size

number

default:"512"

Maximum HTTP request body size in megabytes. Increase this when uploading large S3 objects or Lambda deployment packages.

Environment variable reference

Variable	Default	Description
`FLOCI_BASE_URL`	`http://localhost:4566`	Base URL for callback and response URLs
`FLOCI_HOSTNAME`	(unset)	Override hostname in response URLs (for multi-container Compose)
`FLOCI_DEFAULT_REGION`	`us-east-1`	AWS region in ARNs
`FLOCI_DEFAULT_ACCOUNT_ID`	`000000000000`	AWS account ID in ARNs
`FLOCI_MAX_REQUEST_SIZE`	`512`	Max HTTP request body (MB)
`FLOCI_AUTH_VALIDATE_SIGNATURES`	`false`	Verify AWS SigV4 request signatures
`FLOCI_AUTH_PRESIGN_SECRET`	`local-emulator-secret`	HMAC secret for S3 pre-signed URL verification
`FLOCI_STORAGE_MODE`	`memory`	Global storage mode
`FLOCI_STORAGE_PERSISTENT_PATH`	`./data`	Directory for persistent and hybrid storage
`FLOCI_STORAGE_WAL_COMPACTION_INTERVAL_MS`	`30000`	WAL compaction interval (ms)
`FLOCI_INIT_HOOKS_SHELL_EXECUTABLE`	`/bin/bash`	Shell for hook scripts
`FLOCI_INIT_HOOKS_TIMEOUT_SECONDS`	`30`	Max execution time per hook script
`FLOCI_INIT_HOOKS_SHUTDOWN_GRACE_PERIOD_SECONDS`	`2`	Grace period for shutdown hooks
`FLOCI_SERVICES_SSM_MAX_PARAMETER_HISTORY`	`5`	Max SSM parameter versions kept
`FLOCI_SERVICES_SQS_DEFAULT_VISIBILITY_TIMEOUT`	`30`	SQS visibility timeout (seconds)
`FLOCI_SERVICES_SQS_MAX_MESSAGE_SIZE`	`262144`	SQS max message size (bytes)
`FLOCI_SERVICES_S3_DEFAULT_PRESIGN_EXPIRY_SECONDS`	`3600`	S3 pre-signed URL default expiry
`FLOCI_SERVICES_DYNAMODB_MAX_ITEM_SIZE`	`400000`	DynamoDB max item size (bytes)
`FLOCI_SERVICES_LAMBDA_DOCKER_HOST`	`unix:///var/run/docker.sock`	Docker host for Lambda containers
`FLOCI_SERVICES_LAMBDA_EPHEMERAL`	`false`	Remove Lambda containers after each invocation
`FLOCI_SERVICES_LAMBDA_DEFAULT_MEMORY_MB`	`128`	Default Lambda memory (MB)
`FLOCI_SERVICES_LAMBDA_DEFAULT_TIMEOUT_SECONDS`	`3`	Default Lambda timeout (seconds)
`FLOCI_SERVICES_LAMBDA_CODE_PATH`	`./data/lambda-code`	Directory for Lambda ZIP archives
`FLOCI_SERVICES_LAMBDA_RUNTIME_API_BASE_PORT`	`9200`	Start of Lambda Runtime API port range
`FLOCI_SERVICES_LAMBDA_RUNTIME_API_MAX_PORT`	`9299`	End of Lambda Runtime API port range
`FLOCI_SERVICES_LAMBDA_CONTAINER_IDLE_TIMEOUT_SECONDS`	`300`	Idle Lambda container eviction time
`FLOCI_SERVICES_ELASTICACHE_PROXY_BASE_PORT`	`6379`	First ElastiCache proxy port
`FLOCI_SERVICES_ELASTICACHE_PROXY_MAX_PORT`	`6399`	Last ElastiCache proxy port
`FLOCI_SERVICES_ELASTICACHE_DEFAULT_IMAGE`	`valkey/valkey:8`	Default Valkey/Redis Docker image
`FLOCI_SERVICES_RDS_PROXY_BASE_PORT`	`7001`	First RDS proxy port
`FLOCI_SERVICES_RDS_PROXY_MAX_PORT`	`7099`	Last RDS proxy port
`FLOCI_SERVICES_RDS_DEFAULT_POSTGRES_IMAGE`	`postgres:16-alpine`	Default PostgreSQL Docker image
`FLOCI_SERVICES_RDS_DEFAULT_MYSQL_IMAGE`	`mysql:8.0`	Default MySQL Docker image
`FLOCI_SERVICES_RDS_DEFAULT_MARIADB_IMAGE`	`mariadb:11`	Default MariaDB Docker image
`FLOCI_SERVICES_DOCKER_NETWORK`	(none)	Docker network for Lambda, RDS, ElastiCache containers
`FLOCI_SERVICES_ACM_VALIDATION_WAIT_SECONDS`	`0`	Delay before ACM cert transitions to ISSUED
`FLOCI_SERVICES_CLOUDWATCHLOGS_MAX_EVENTS_PER_QUERY`	`10000`	Max events per CloudWatch Logs query
`FLOCI_SERVICES_SECRETSMANAGER_DEFAULT_RECOVERY_WINDOW_DAYS`	`30`	Default secret recovery window

Auth settings

FLOCI_AUTH_VALIDATE_SIGNATURES defaults to false. This means any credentials are accepted, which is appropriate for local development. Set it to true only when you need to test SigV4 signing logic, as it requires properly signed requests.

floci:
  auth:
    validate-signatures: false        # Set true to enforce SigV4 signing
    presign-secret: local-emulator-secret

Disabling services

Set enabled: false for any service you don’t need. Disabled services return ServiceUnavailableException rather than silently ignoring calls, so you’ll catch misconfigurations early.

floci:
  services:
    cloudformation:
      enabled: false
    stepfunctions:
      enabled: false
    opensearch:
      enabled: false

The equivalent via environment variables:

FLOCI_SERVICES_CLOUDFORMATION_ENABLED=false
FLOCI_SERVICES_STEPFUNCTIONS_ENABLED=false

Full application.yml reference

Complete application.yml with all defaults

floci:
  base-url: "http://localhost:4566"  # Used to build callback URLs (e.g. SNS subscription endpoints)
  default-region: us-east-1
  default-account-id: "000000000000"
  max-request-size: 512              # Max HTTP request body size in MB (default 512 MB)

  auth:
    validate-signatures: false        # Set to true to enforce AWS request signing
    presign-secret: local-emulator-secret  # HMAC secret for S3 pre-signed URL verification

  init-hooks:
    shell-executable: /bin/bash
    timeout-seconds: 30
    shutdown-grace-period-seconds: 2

  storage:
    mode: memory                      # memory | persistent | hybrid | wal
    persistent-path: ./data
    wal:
      compaction-interval-ms: 30000
    services:
      ssm:
        flush-interval-ms: 5000
      dynamodb:
        flush-interval-ms: 5000
      sns:
        flush-interval-ms: 5000
      lambda:
        flush-interval-ms: 5000
      cloudwatchlogs:
        flush-interval-ms: 5000
      cloudwatchmetrics:
        flush-interval-ms: 5000
      secretsmanager:
        flush-interval-ms: 5000
      opensearch:
        flush-interval-ms: 5000

  services:
    ssm:
      enabled: true
      max-parameter-history: 5        # Max versions kept per parameter

    sqs:
      enabled: true
      default-visibility-timeout: 30  # Seconds
      max-message-size: 262144        # Bytes (256 KB)

    s3:
      enabled: true
      default-presign-expiry-seconds: 3600

    dynamodb:
      enabled: true

    sns:
      enabled: true

    lambda:
      enabled: true
      ephemeral: false                # true = remove container after each invocation
      default-memory-mb: 128
      default-timeout-seconds: 3
      docker-host: unix:///var/run/docker.sock
      runtime-api-base-port: 9200    # Port range for Lambda Runtime API
      runtime-api-max-port: 9299
      code-path: ./data/lambda-code  # Where ZIP archives are stored
      poll-interval-ms: 1000
      container-idle-timeout-seconds: 300  # Remove idle containers after this

    apigateway:
      enabled: true

    iam:
      enabled: true

    elasticache:
      enabled: true
      proxy-base-port: 6379
      proxy-max-port: 6399
      default-image: "valkey/valkey:8"

    rds:
      enabled: true
      proxy-base-port: 7001
      proxy-max-port: 7099
      default-postgres-image: "postgres:16-alpine"
      default-mysql-image: "mysql:8.0"
      default-mariadb-image: "mariadb:11"

    eventbridge:
      enabled: true

    cloudwatchlogs:
      enabled: true
      max-events-per-query: 10000

    cloudwatchmetrics:
      enabled: true

    secretsmanager:
      enabled: true
      default-recovery-window-days: 30

    kinesis:
      enabled: true

    kms:
      enabled: true

    cognito:
      enabled: true

    stepfunctions:
      enabled: true

    cloudformation:
      enabled: true

    acm:
      enabled: true
      validation-wait-seconds: 0  # Seconds before transitioning PENDING_VALIDATION → ISSUED

    ses:
      enabled: true

    opensearch:
      enabled: true
      mode: mock                                    # mock | real
      default-image: "opensearchproject/opensearch:2"
      proxy-base-port: 9400
      proxy-max-port: 9499

Get Started

Configuration

Services

Contributing

Configuration overview

Core settings

Environment variable reference

Auth settings

Disabling services

Full application.yml reference

Build docs developers (and LLMs) love

Get Started

Configuration

Services

Contributing

​Core settings

​Environment variable reference

​Auth settings

​Disabling services

​Full application.yml reference

Build docs developers (and LLMs) love

Core settings

Environment variable reference

Auth settings

Disabling services

Full application.yml reference