Skip to content

armgit / floci

Public Imported from GitHub
0

Light, fluffy, and always free - The AWS Local Emulator alternative

Docs/enviroment instead yml (#764)

Hector Ventura9e35046647ea
diff --git a/README.md b/README.md
index 7c6cba60d6..774b4502a0 100644
--- a/README.md
+++ b/README.md
@@ -279,6 +279,20 @@ Floci features a flexible storage architecture designed to balance developer pro
For more details, visit the [Storage Configuration documentation](https://floci.io/floci/configuration/storage/).
+## Multi-Account Isolation
+
+Floci supports full per-account resource isolation with no extra configuration. If your AWS access key ID is **exactly 12 digits**, Floci uses it directly as the account ID — resources created by one account are completely invisible to another.
+
+```bash
+# Two accounts, full isolation — same queue name, separate namespaces
+AWS_ACCESS_KEY_ID=111111111111 aws sqs create-queue --queue-name orders
+AWS_ACCESS_KEY_ID=222222222222 aws sqs create-queue --queue-name orders
+```
+
+Any other key format (e.g. `test`, `AKIA…`) falls back to `FLOCI_DEFAULT_ACCOUNT_ID` (`000000000000` by default) — the standard single-account setup.
+
+→ [Multi-Account Isolation docs](https://floci.io/floci/configuration/multi-account/)
+
## Quick Start
```yaml
diff --git a/docker/run-docker-tests.sh b/docker/run-docker-tests.sh
index 9fcb66ac1d..3106cc746c 100644
--- a/docker/run-docker-tests.sh
+++ b/docker/run-docker-tests.sh
@@ -48,16 +48,12 @@ for suite in "${SUITES[@]}"; do
# Build
docker build -q -t "$IMAGE_NAME" "compatibility-tests/$suite"
- EXTRA_ARGS=""
- if [ "$suite" = "compat-cdk" ]; then
- EXTRA_ARGS="-v /var/run/docker.sock:/var/run/docker.sock --group-add $DOCKER_GID"
- fi
-
# Run
docker run --rm --network "$NETWORK" \
-e FLOCI_ENDPOINT=http://floci:4566 \
-v "$(pwd)/test-results:/results" \
- $EXTRA_ARGS \
+ -v /var/run/docker.sock:/var/run/docker.sock \
+ --group-add "$DOCKER_GID" \
"$IMAGE_NAME" || echo "Test suite $suite failed"
done
diff --git a/docs/configuration/advanced/application-yml.md b/docs/configuration/advanced/application-yml.md
new file mode 100644
index 0000000000..d4fdf3f21a
--- /dev/null
+++ b/docs/configuration/advanced/application-yml.md
@@ -0,0 +1,334 @@
+# application.yml Reference
+
+!!! note "Source builds only"
+ This page is for users who build Floci from source or mount a custom `application.yml` into the container. **If you run the published Docker image, you don't need this file** — all settings are configured through `FLOCI_*` environment variables. See the [Environment Variables Reference](../environment-variables.md) for the complete list.
+
+All settings can be provided as YAML (in `src/main/resources/application.yml` or mounted as a config file) or overridden via environment variables using the `FLOCI_` prefix with dots and dashes replaced by underscores.
+
+## URL configuration
+
+Floci generates absolute URLs for certain response fields (SQS queue URLs, SNS
+subscription endpoints, pre-signed S3 URLs). Two settings control the hostname
+embedded in those URLs:
+
+| Setting | Env variable | Default | Description |
+|---|---|---|---|
+| `floci.base-url` | `FLOCI_BASE_URL` | `http://localhost:4566` | Full base URL used to build response URLs. Change the scheme, host, and port together. |
+| `floci.hostname` | `FLOCI_HOSTNAME` | _(none)_ | Override only the hostname in `base-url`. Useful in Docker Compose where `localhost` is unreachable from other containers. |
+
+When `floci.hostname` is set it replaces just the host portion of `base-url`,
+leaving the scheme and port unchanged. Setting `FLOCI_HOSTNAME: floci` is
+equivalent to changing `base-url` from `http://localhost:4566` to
+`http://floci:4566`.
+
+**Example — Docker Compose multi-container setup:**
+
+```yaml
+environment:
+ FLOCI_HOSTNAME: floci # matches the compose service name
+```
+
+See [Docker Compose — Multi-container networking](../docker-compose.md#multi-container-networking) for a full example.
+
+## Full Reference
+
+The block below mirrors `src/main/resources/application.yml`, it's the effective set of keys Floci ships with. Some supported keys are omitted here (for example `floci.init-hooks.*`) but can still be provided via YAML or environment variables.
+
+```yaml
+floci:
+ max-request-size: 512 # Max HTTP request body size in MB
+ base-url: "http://localhost:4566" # Used to build response URLs (SQS QueueUrl, SNS endpoints, etc.)
+ # hostname: "" # When set, overrides the host in base-url for multi-container Docker
+ default-region: us-east-1
+ default-account-id: "000000000000"
+
+ 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
+ acm:
+ flush-interval-ms: 5000
+ opensearch:
+ flush-interval-ms: 5000
+
+ dns:
+ # Extra hostname suffixes resolved to Floci's container IP by the embedded DNS server.
+ # The primary suffix (floci.hostname or derived from base-url) is always included.
+ # Useful when migrating from LocalStack — Lambda functions that hardcode
+ # localhost.localstack.cloud as their endpoint work without code changes.
+ # Via env var (comma-separated): FLOCI_DNS_EXTRA_SUFFIXES=localhost.localstack.cloud,other.internal
+ # extra-suffixes:
+ # - localhost.localstack.cloud
+
+ auth:
+ validate-signatures: false # Set to true to enforce AWS SigV4 validation
+ presign-secret: local-emulator-secret # HMAC secret for S3 pre-signed URL verification
+
+ tls:
+ enabled: false # FLOCI_TLS_ENABLED — enable HTTPS on all endpoints
+ # cert-path: "" # FLOCI_TLS_CERT_PATH — PEM certificate file path
+ # key-path: "" # FLOCI_TLS_KEY_PATH — PEM private key file path
+ self-signed: true # FLOCI_TLS_SELF_SIGNED — auto-generate cert when no paths provided
+
+ docker:
+ log-max-size: "10m" # Max size per container log file before rotation
+ log-max-file: "3" # Number of rotated log files to retain
+ docker-host: unix:///var/run/docker.sock # Docker daemon socket (shared by Lambda, RDS, ElastiCache)
+ docker-config-path: "" # Path to dir containing Docker's config.json (e.g. /root/.docker)
+ registry-credentials: [] # Per-registry explicit credentials for private registries
+
+ 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)
+ clear-fifo-deduplication-cache-on-purge: false # When true, PurgeQueue clears SQS FIFO dedup and SNS FIFO topic dedup for topics subscribed to that queue
+
+ 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
+ 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
+ region-concurrency-limit: 1000 # Concurrent executions ceiling per region
+ unreserved-concurrency-min: 100 # Minimum unreserved capacity PutFunctionConcurrency must leave
+ hot-reload:
+ enabled: false # true = enable bind-mount hot-reload via S3Bucket=hot-reload
+ # allowed-paths: # Optional allowlist of host paths that may be bind-mounted
+ # - /home/user/projects
+ # - /tmp
+
+ apigateway:
+ enabled: true
+
+ apigatewayv2:
+ enabled: true
+
+ iam:
+ enabled: true
+ enforcement-enabled: false # Set to true to enforce IAM policies on all requests
+
+ 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
+
+ scheduler:
+ 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
+ # smtp-host: mailpit # SMTP server for email relay (empty = store only)
+ # smtp-port: 1025
+ # smtp-user: ""
+ # smtp-pass: ""
+ # smtp-starttls: DISABLED # DISABLED, OPTIONAL, or REQUIRED
+
+ opensearch:
+ enabled: true
+ mock: false # true = metadata only, no Docker (useful for CI)
+ default-image: "opensearchproject/opensearch:2"
+ proxy-base-port: 9400
+ proxy-max-port: 9499
+ keep-running-on-shutdown: false # leave containers running after Floci stops
+ # docker network is inherited from floci.services.docker-network
+
+ ec2:
+ enabled: true
+
+ ecs:
+ enabled: true
+ mock: false # true = tasks go to RUNNING without Docker (useful for CI)
+
+ appconfig:
+ enabled: true
+
+ appconfigdata:
+ enabled: true
+
+ ecr:
+ enabled: true
+ registry-image: "registry:2"
+ registry-container-name: floci-ecr-registry
+ registry-base-port: 5100
+ registry-max-port: 5199
+ data-path: ./data/ecr
+ tls-enabled: false
+ keep-running-on-shutdown: true
+ uri-style: hostname # hostname | path
+```
+
+### Initialization hooks
+
+`floci.init-hooks.*` is accepted as an override but is not declared in the shipped `application.yml`. See [Initialization Hooks](../initialization-hooks.md) for the full list of keys (`shell-executable`, `timeout-seconds`, `shutdown-grace-period-seconds`) and their defaults.
+
+## Service Limits
+
+All keys in this table are declared on `EmulatorConfig` and accept environment variable overrides via the `FLOCI_` prefix.
+
+| Variable | Default | Description |
+|----------------------------------------------------|------------------|---------------------------------------------------------------|
+| `FLOCI_MAX_REQUEST_SIZE` | `512` | Max HTTP request body size in MB |
+| `FLOCI_DEFAULT_REGION` | `us-east-1` | Default AWS region used in ARNs and response URLs |
+| `FLOCI_DEFAULT_AVAILABILITY_ZONE` | `us-east-1a` | Default AZ reported by EC2, RDS, and other AZ-aware services |
+| `FLOCI_DEFAULT_ACCOUNT_ID` | `000000000000` | Default AWS account ID used in ARNs |
+| `FLOCI_ECR_BASE_URI` | `public.ecr.aws` | Base URI used when pulling container images (e.g. Lambda) |
+| `FLOCI_DNS_EXTRA_SUFFIXES` | *(unset)* | Comma-separated extra hostname suffixes the embedded DNS server resolves to Floci's container IP. E.g. `localhost.localstack.cloud,localhost.example.internal` |
+| `FLOCI_SERVICES_SSM_MAX_PARAMETER_HISTORY` | `5` | Max parameter versions kept |
+| `FLOCI_SERVICES_SQS_DEFAULT_VISIBILITY_TIMEOUT` | `30` | Default visibility timeout (seconds) |
+| `FLOCI_SERVICES_SQS_MAX_MESSAGE_SIZE` | `262144` | Max message size (bytes) |
+| `FLOCI_SERVICES_SQS_CLEAR_FIFO_DEDUPLICATION_CACHE_ON_PURGE` | `false` | When `true`, `PurgeQueue` clears the FIFO 5-minute deduplication cache for the target queue and matching SNS FIFO topic dedup entries |
+| `FLOCI_SERVICES_S3_DEFAULT_PRESIGN_EXPIRY_SECONDS` | `3600` | Pre-signed URL expiry |
+| `FLOCI_SERVICES_DOCKER_NETWORK` | *(unset)* | Shared Docker network for Lambda, RDS, ElastiCache containers |
+| `FLOCI_SERVICES_ECS_MOCK` | `false` | Skip Docker; tasks go straight to RUNNING (useful for CI) |
+| `FLOCI_SERVICES_ECS_DOCKER_NETWORK` | *(unset)* | Docker network for ECS task containers |
+| `FLOCI_SERVICES_ECS_DEFAULT_MEMORY_MB` | `512` | Default memory (MB) when task definition omits it |
+| `FLOCI_SERVICES_ECS_DEFAULT_CPU_UNITS` | `256` | Default CPU units when task definition omits it |
+| `FLOCI_SERVICES_IAM_ENFORCEMENT_ENABLED` | `false` | Enforce IAM identity-based policies on every request when `true` |
+| `FLOCI_SERVICES_OPENSEARCH_MOCK` | `false` | Skip Docker; domains appear active immediately (useful for CI) |
+| `FLOCI_SERVICES_OPENSEARCH_KEEP_RUNNING_ON_SHUTDOWN` | `false` | Leave OpenSearch containers running after Floci stops |
+| `FLOCI_SERVICES_SES_SMTP_HOST` | *(unset)* | SMTP server host for SES email relay (empty = store only) |
+| `FLOCI_SERVICES_SES_SMTP_PORT` | `25` | SMTP server port |
+| `FLOCI_SERVICES_SES_SMTP_USER` | *(unset)* | SMTP authentication username |
+| `FLOCI_SERVICES_SES_SMTP_PASS` | *(unset)* | SMTP authentication password |
+| `FLOCI_SERVICES_SES_SMTP_STARTTLS` | `DISABLED` | STARTTLS mode: `DISABLED`, `OPTIONAL`, or `REQUIRED` |
+| `FLOCI_SERVICES_LAMBDA_HOT_RELOAD_ENABLED` | `false` | Enable bind-mount hot-reload mode (`S3Bucket=hot-reload`) |
+| `FLOCI_SERVICES_LAMBDA_HOT_RELOAD_ALLOWED_PATHS` | *(unset)* | Comma-separated list of host paths allowed as bind-mount roots; unset = any absolute path |
+
+Per-queue SQS redrive policy (`maxReceiveCount`) is configured at queue creation time via `SetQueueAttributes` / `CreateQueue`, not as a global default.
+
+`FLOCI_DEFAULT_AVAILABILITY_ZONE` and `FLOCI_ECR_BASE_URI` are declared in `EmulatorConfig` but not in the shipped `application.yml`, so they fall through to the `@WithDefault` values above when unset.
+
+## Disabling Services
+
+Set `enabled: false` for any service you don't need. Disabled services return a `ServiceUnavailableException` rather than silently ignoring calls.
+
+```yaml
+floci:
+ services:
+ cloudformation:
+ enabled: false
+ stepfunctions:
+ enabled: false
+```
+
+Via environment variable — set to `false` for any `FLOCI_SERVICES_<SERVICE>_ENABLED` key. See [Environment Variables Reference](../environment-variables.md#services-core) for the full list.
+
+## Logging
+
+Floci uses standard [Quarkus logging](https://quarkus.io/guides/logging). The default effective level is `INFO`. Each service logs operation-level events at `DEBUG` (IDs and target resources) and full request/response payloads at `TRACE` — useful when diagnosing TestContainers-based test failures.
+
+Floci ships with `quarkus.log.min-level: TRACE`, so raising a single category to `TRACE` is enough; you don't need to change the min-level yourself.
+
+**Enable TRACE for a service via environment variables:**
+
+```bash
+# SQS: log SendMessage/ReceiveMessage/DeleteMessage bodies and attributes
+QUARKUS_LOG_CATEGORY__IO_GITHUB_HECTORVENT_FLOCI_SERVICES_SQS__LEVEL=TRACE
+
+# DynamoDB: log PutItem/GetItem/UpdateItem/DeleteItem items, Query/Scan counts
+QUARKUS_LOG_CATEGORY__IO_GITHUB_HECTORVENT_FLOCI_SERVICES_DYNAMODB__LEVEL=TRACE
+```
+
+**Or in `application.yml`:**
+
+```yaml
+quarkus:
+ log:
+ category:
+ "io.github.hectorvent.floci.services.sqs":
+ level: TRACE
+ "io.github.hectorvent.floci.services.dynamodb":
+ level: TRACE
+```
+
+**TestContainers example:**
+
+```java
+new GenericContainer<>("floci/floci:latest")
+ .withExposedPorts(4566)
+ .withEnv("QUARKUS_LOG_CATEGORY__IO_GITHUB_HECTORVENT_FLOCI_SERVICES_SQS__LEVEL", "TRACE");
+```
+
+TRACE output includes the payload alongside the existing DEBUG line:
+
+```
+DEBUG [SqsService] Sent message aa7b93e7-... to queue .../events
+TRACE [SqsService] Sent message aa7b93e7-... to queue .../events body={"eventType":"..."} attributes={source=okta}
+```
diff --git a/docs/configuration/application-yml.md b/docs/configuration/application-yml.md
index a05a38f07c..c608849277 100644
--- a/docs/configuration/application-yml.md
+++ b/docs/configuration/application-yml.md
@@ -1,323 +1,6 @@
# application.yml Reference
-All settings can be provided as YAML (mounted as a config file or in `src/main/resources/application.yml`) or overridden via environment variables (`FLOCI_` prefix, dots/dashes replaced with underscores).
+!!! note "Moved"
+ This page has moved to [Advanced → application.yml Reference](./advanced/application-yml.md).
-## URL configuration
-
-Floci generates absolute URLs for certain response fields (SQS queue URLs, SNS
-subscription endpoints, pre-signed S3 URLs). Two settings control the hostname
-embedded in those URLs:
-
-| Setting | Env variable | Default | Description |
-|---|---|---|---|
-| `floci.base-url` | `FLOCI_BASE_URL` | `http://localhost:4566` | Full base URL used to build response URLs. Change the scheme, host, and port together. |
-| `floci.hostname` | `FLOCI_HOSTNAME` | _(none)_ | Override only the hostname in `base-url`. Useful in Docker Compose where `localhost` is unreachable from other containers. |
-
-When `floci.hostname` is set it replaces just the host portion of `base-url`,
-leaving the scheme and port unchanged. Setting `FLOCI_HOSTNAME: floci` is
-equivalent to changing `base-url` from `http://localhost:4566` to
-`http://floci:4566`.
-
-**Example — Docker Compose multi-container setup:**
-
-```yaml
-environment:
- FLOCI_HOSTNAME: floci # matches the compose service name
-```
-
-See [Docker Compose — Multi-container networking](./docker-compose.md#multi-container-networking) for a full example.
-
-## Full Reference
-
-The block below mirrors `src/main/resources/application.yml`, it's the effective set of keys Floci ships with. Some supported keys are omitted here (for example `floci.init-hooks.*`) but can still be provided via YAML or environment variables.
-
-```yaml
-floci:
- max-request-size: 512 # Max HTTP request body size in MB
- base-url: "http://localhost:4566" # Used to build response URLs (SQS QueueUrl, SNS endpoints, etc.)
- # hostname: "" # When set, overrides the host in base-url for multi-container Docker
- default-region: us-east-1
- default-account-id: "000000000000"
-
- 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
- acm:
- flush-interval-ms: 5000
- opensearch:
- flush-interval-ms: 5000
-
- dns:
- # Extra hostname suffixes resolved to Floci's container IP by the embedded DNS server.
- # The primary suffix (floci.hostname or derived from base-url) is always included.
- # Useful when migrating from LocalStack — Lambda functions that hardcode
- # localhost.localstack.cloud as their endpoint work without code changes.
- # Via env var (comma-separated): FLOCI_DNS_EXTRA_SUFFIXES=localhost.localstack.cloud,other.internal
- # extra-suffixes:
- # - localhost.localstack.cloud
-
- auth:
- validate-signatures: false # Set to true to enforce AWS SigV4 validation
- presign-secret: local-emulator-secret # HMAC secret for S3 pre-signed URL verification
-
- docker:
- log-max-size: "10m" # Max size per container log file before rotation
- log-max-file: "3" # Number of rotated log files to retain
- docker-host: unix:///var/run/docker.sock # Docker daemon socket (shared by Lambda, RDS, ElastiCache)
- docker-config-path: "" # Path to dir containing Docker's config.json (e.g. /root/.docker)
- registry-credentials: [] # Per-registry explicit credentials for private registries
-
- 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)
- clear-fifo-deduplication-cache-on-purge: false # When true, PurgeQueue clears SQS FIFO dedup and SNS FIFO topic dedup for topics subscribed to that queue
-
- 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
- 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
- region-concurrency-limit: 1000 # Concurrent executions ceiling per region
- unreserved-concurrency-min: 100 # Minimum unreserved capacity PutFunctionConcurrency must leave
- hot-reload:
- enabled: false # true = enable bind-mount hot-reload via S3Bucket=hot-reload
- # allowed-paths: # Optional allowlist of host paths that may be bind-mounted
- # - /home/user/projects
- # - /tmp
-
- apigateway:
- enabled: true
-
- apigatewayv2:
- enabled: true
-
- iam:
- enabled: true
- enforcement-enabled: false # Set to true to enforce IAM policies on all requests
-
- 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
-
- scheduler:
- 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
- # smtp-host: mailpit # SMTP server for email relay (empty = store only)
- # smtp-port: 1025
- # smtp-user: ""
- # smtp-pass: ""
- # smtp-starttls: DISABLED # DISABLED, OPTIONAL, or REQUIRED
-
- opensearch:
- enabled: true
- mock: false # true = metadata only, no Docker (useful for CI)
- default-image: "opensearchproject/opensearch:2"
- proxy-base-port: 9400
- proxy-max-port: 9499
- keep-running-on-shutdown: false # leave containers running after Floci stops
- # docker network is inherited from floci.services.docker-network
-
- ec2:
- enabled: true
-
- ecs:
- enabled: true
- mock: false # true = tasks go to RUNNING without Docker (useful for CI)
-
- appconfig:
- enabled: true
-
- appconfigdata:
- enabled: true
-
- ecr:
- enabled: true
- registry-image: "registry:2"
- registry-container-name: floci-ecr-registry
- registry-base-port: 5100
- registry-max-port: 5199
- data-path: ./data/ecr
- tls-enabled: false
- keep-running-on-shutdown: true
- uri-style: hostname # hostname | path
-```
-
-### Initialization hooks
-
-`floci.init-hooks.*` is accepted as an override but is not declared in the shipped `application.yml`. See [Initialization Hooks](./initialization-hooks.md) for the full list of keys (`shell-executable`, `timeout-seconds`, `shutdown-grace-period-seconds`) and their defaults.
-
-## Service Limits
-
-All keys in this table are declared on `EmulatorConfig` and accept environment variable overrides via the `FLOCI_` prefix.
-
-| Variable | Default | Description |
-|----------------------------------------------------|------------------|---------------------------------------------------------------|
-| `FLOCI_MAX_REQUEST_SIZE` | `512` | Max HTTP request body size in MB |
-| `FLOCI_DEFAULT_REGION` | `us-east-1` | Default AWS region used in ARNs and response URLs |
-| `FLOCI_DEFAULT_AVAILABILITY_ZONE` | `us-east-1a` | Default AZ reported by EC2, RDS, and other AZ-aware services |
-| `FLOCI_DEFAULT_ACCOUNT_ID` | `000000000000` | Default AWS account ID used in ARNs |
-| `FLOCI_ECR_BASE_URI` | `public.ecr.aws` | Base URI used when pulling container images (e.g. Lambda) |
-| `FLOCI_DNS_EXTRA_SUFFIXES` | *(unset)* | Comma-separated extra hostname suffixes the embedded DNS server resolves to Floci's container IP. E.g. `localhost.localstack.cloud,localhost.example.internal` |
-| `FLOCI_SERVICES_SSM_MAX_PARAMETER_HISTORY` | `5` | Max parameter versions kept |
-| `FLOCI_SERVICES_SQS_DEFAULT_VISIBILITY_TIMEOUT` | `30` | Default visibility timeout (seconds) |
-| `FLOCI_SERVICES_SQS_MAX_MESSAGE_SIZE` | `262144` | Max message size (bytes) |
-| `FLOCI_SERVICES_SQS_CLEAR_FIFO_DEDUPLICATION_CACHE_ON_PURGE` | `false` | When `true`, `PurgeQueue` clears the FIFO 5-minute deduplication cache for the target queue and matching SNS FIFO topic dedup entries |
-| `FLOCI_SERVICES_S3_DEFAULT_PRESIGN_EXPIRY_SECONDS` | `3600` | Pre-signed URL expiry |
-| `FLOCI_SERVICES_DOCKER_NETWORK` | *(unset)* | Shared Docker network for Lambda, RDS, ElastiCache containers |
-| `FLOCI_SERVICES_ECS_MOCK` | `false` | Skip Docker; tasks go straight to RUNNING (useful for CI) |
-| `FLOCI_SERVICES_ECS_DOCKER_NETWORK` | *(unset)* | Docker network for ECS task containers |
-| `FLOCI_SERVICES_ECS_DEFAULT_MEMORY_MB` | `512` | Default memory (MB) when task definition omits it |
-| `FLOCI_SERVICES_ECS_DEFAULT_CPU_UNITS` | `256` | Default CPU units when task definition omits it |
-| `FLOCI_SERVICES_IAM_ENFORCEMENT_ENABLED` | `false` | Enforce IAM identity-based policies on every request when `true` |
-| `FLOCI_SERVICES_OPENSEARCH_MOCK` | `false` | Skip Docker; domains appear active immediately (useful for CI) |
-| `FLOCI_SERVICES_OPENSEARCH_KEEP_RUNNING_ON_SHUTDOWN` | `false` | Leave OpenSearch containers running after Floci stops |
-| `FLOCI_SERVICES_SES_SMTP_HOST` | *(unset)* | SMTP server host for SES email relay (empty = store only) |
-| `FLOCI_SERVICES_SES_SMTP_PORT` | `25` | SMTP server port |
-| `FLOCI_SERVICES_SES_SMTP_USER` | *(unset)* | SMTP authentication username |
-| `FLOCI_SERVICES_SES_SMTP_PASS` | *(unset)* | SMTP authentication password |
-| `FLOCI_SERVICES_SES_SMTP_STARTTLS` | `DISABLED` | STARTTLS mode: `DISABLED`, `OPTIONAL`, or `REQUIRED` |
-| `FLOCI_SERVICES_LAMBDA_HOT_RELOAD_ENABLED` | `false` | Enable bind-mount hot-reload mode (`S3Bucket=hot-reload`) |
-| `FLOCI_SERVICES_LAMBDA_HOT_RELOAD_ALLOWED_PATHS` | *(unset)* | Comma-separated list of host paths allowed as bind-mount roots; unset = any absolute path |
-
-Per-queue SQS redrive policy (`maxReceiveCount`) is configured at queue creation time via `SetQueueAttributes` / `CreateQueue`, not as a global default.
-
-`FLOCI_DEFAULT_AVAILABILITY_ZONE` and `FLOCI_ECR_BASE_URI` are declared in `EmulatorConfig` but not in the shipped `application.yml`, so they fall through to the `@WithDefault` values above when unset.
-
-## Disabling Services
-
-Set `enabled: false` for any service you don't need. Disabled services return a `ServiceUnavailableException` rather than silently ignoring calls.
-
-```yaml
-floci:
- services:
- cloudformation:
- enabled: false
- stepfunctions:
- enabled: false
-```
-
-## Logging
-
-Floci uses standard [Quarkus logging](https://quarkus.io/guides/logging). The default effective level is `INFO`. Each service logs operation-level events at `DEBUG` (IDs and target resources) and full request/response payloads at `TRACE` — useful when diagnosing TestContainers-based test failures.
-
-Floci ships with `quarkus.log.min-level: TRACE`, so raising a single category to `TRACE` is enough; you don't need to change the min-level yourself.
-
-**Enable TRACE for a service via environment variables:**
-
-```bash
-# SQS: log SendMessage/ReceiveMessage/DeleteMessage bodies and attributes
-QUARKUS_LOG_CATEGORY__IO_GITHUB_HECTORVENT_FLOCI_SERVICES_SQS__LEVEL=TRACE
-
-# DynamoDB: log PutItem/GetItem/UpdateItem/DeleteItem items, Query/Scan counts
-QUARKUS_LOG_CATEGORY__IO_GITHUB_HECTORVENT_FLOCI_SERVICES_DYNAMODB__LEVEL=TRACE
-```
-
-**Or in `application.yml`:**
-
-```yaml
-quarkus:
- log:
- category:
- "io.github.hectorvent.floci.services.sqs":
- level: TRACE
- "io.github.hectorvent.floci.services.dynamodb":
- level: TRACE
-```
-
-**TestContainers example:**
-
-```java
-new GenericContainer<>("floci/floci:latest")
- .withExposedPorts(4566)
- .withEnv("QUARKUS_LOG_CATEGORY__IO_GITHUB_HECTORVENT_FLOCI_SERVICES_SQS__LEVEL", "TRACE");
-```
-
-TRACE output includes the payload alongside the existing DEBUG line:
-
-```
-DEBUG [SqsService] Sent message aa7b93e7-... to queue .../events
-TRACE [SqsService] Sent message aa7b93e7-... to queue .../events body={"eventType":"..."} attributes={source=okta}
-```
\ No newline at end of file
+ If you run the published Docker image, you don't need an `application.yml` — all settings are configured through `FLOCI_*` environment variables. See the [Environment Variables Reference](./environment-variables.md).
diff --git a/docs/configuration/docker-compose.md b/docs/configuration/docker-compose.md
index a546dda116..18aa3cb813 100644
--- a/docs/configuration/docker-compose.md
+++ b/docs/configuration/docker-compose.md
@@ -1,8 +1,18 @@
-# Docker Compose
+# Running with Docker
-## Minimal Setup
+Floci is distributed as a Docker image. All configuration is done through environment variables — no config files or volume-mounted YAML is required.
-For most services (SSM, SQS, SNS, S3, DynamoDB, Lambda, API Gateway, Cognito, KMS, Kinesis, Secrets Manager, CloudFormation, Step Functions, IAM, STS, EventBridge, Scheduler, CloudWatch) a single port is enough:
+## Quick Start
+
+```bash
+docker run --rm -p 4566:4566 floci/floci:latest
+```
+
+That's it. The default configuration works out of the box for most services: SQS, SNS, S3, DynamoDB, SSM, Lambda, API Gateway, Cognito, KMS, Kinesis, Secrets Manager, CloudFormation, Step Functions, IAM, STS, EventBridge, Scheduler, and CloudWatch.
+
+## Docker Compose
+
+### Minimal (stateless)
```yaml title="docker-compose.yml"
services:
@@ -10,51 +20,67 @@ services:
image: floci/floci:latest
ports:
- "4566:4566"
- volumes:
- - ./data:/app/data
- - ./init/start.d:/etc/floci/init/start.d:ro
- - ./init/ready.d:/etc/floci/init/ready.d:ro
+ environment:
+ FLOCI_HOSTNAME: floci
```
-## Full Setup (with ElastiCache and RDS)
+### With persistence
-ElastiCache and RDS work by proxying TCP connections to real Docker containers (Valkey/Redis, PostgreSQL, MySQL). Those containers' ports must be reachable from your host, so additional port ranges must be exposed:
+Add two env vars and a volume — no config file needed:
```yaml title="docker-compose.yml"
services:
floci:
image: floci/floci:latest
ports:
- - "4566:4566" # All AWS API calls
- - "6379-6399:6379-6399" # ElastiCache / Redis proxy ports
- - "7001-7099:7001-7099" # RDS / PostgreSQL + MySQL proxy ports
+ - "4566:4566"
volumes:
- - /var/run/docker.sock:/var/run/docker.sock # required for Lambda, ElastiCache, RDS
- - ./data:/app/data
+ - floci-data:/app/data
environment:
- FLOCI_SERVICES_DOCKER_NETWORK: my-project_default # (1)
- FLOCI_HOSTNAME: floci # (2)
+ FLOCI_HOSTNAME: floci
+ FLOCI_STORAGE_MODE: persistent
+ FLOCI_STORAGE_PERSISTENT_PATH: /app/data
+
+volumes:
+ floci-data:
```
-1. Set this to the Docker network name that your compose project creates (usually `<project-name>_default`). Floci uses it to attach spawned Lambda / ElastiCache / RDS containers to the same network.
-2. Set this to the Compose service name when other containers, including
- Lambda containers spawned by Floci, need to call Floci by Docker DNS.
+### With ElastiCache and RDS
+
+ElastiCache and RDS proxy TCP connections to real Docker containers. Those containers' ports must be reachable from your host, so additional port ranges are exposed. The Docker socket is required for Floci to manage those containers:
+
+```yaml title="docker-compose.yml"
+services:
+ floci:
+ image: floci/floci:latest
+ ports:
+ - "4566:4566"
+ - "6379-6399:6379-6399" # ElastiCache proxy ports
+ - "7001-7099:7001-7099" # RDS proxy ports
+ volumes:
+ - /var/run/docker.sock:/var/run/docker.sock
+ - floci-data:/app/data
+ environment:
+ FLOCI_HOSTNAME: floci
+ FLOCI_SERVICES_DOCKER_NETWORK: myproject_default
+ FLOCI_STORAGE_MODE: persistent
+ FLOCI_STORAGE_PERSISTENT_PATH: /app/data
+
+volumes:
+ floci-data:
+```
!!! warning "Docker socket"
- Lambda, ElastiCache, and RDS require access to the Docker socket (`/var/run/docker.sock`) to spawn and manage containers. If you don't use these services, you can omit that volume.
+ Lambda, ElastiCache, RDS, OpenSearch, and MSK require access to the Docker socket (`/var/run/docker.sock`) to spawn and manage containers. If you don't use these services, you can omit that volume.
-!!! note "ECR ports are not listed here intentionally"
- ECR is backed by a separate `registry:2` sidecar container (`floci-ecr-registry`) that Floci starts and manages. That container binds its own host port (default `5100`) directly — adding `5100-5199` to the floci service's `ports` would conflict with the sidecar and break `docker push`/`docker pull`. See [Ports Reference → ECR](./ports.md#ports-51005199--ecr-registry) for details.
+!!! note "ECR port"
+ ECR is backed by a `registry:2` sidecar container (`floci-ecr-registry`) that Floci starts and manages. That container binds its own host port (default `5100`) directly — do not add `5100-5199` to the Floci service's `ports` list. See [Ports Reference → ECR](./ports.md#ports-51005199--ecr-registry).
-## Multi-container networking
+## Multi-container Networking
-By default, Floci embeds `localhost` in response URLs — for example, SQS queue
-URLs look like `http://localhost:4566/000000000000/my-queue`. This is fine when
-your application runs on the same machine, but breaks inside Docker Compose:
-other containers cannot reach `localhost` of the Floci container.
+By default Floci embeds `localhost` in response URLs — for example, SQS queue URLs look like `http://localhost:4566/000000000000/my-queue`. This works when your application runs on the same machine, but breaks inside Docker Compose because other containers cannot reach `localhost` of the Floci container.
-Set `FLOCI_HOSTNAME` to the Compose service name so that Floci uses that name
-in every URL it generates:
+Set `FLOCI_HOSTNAME` to the Compose service name so Floci uses that name in every URL it generates:
```yaml title="docker-compose.yml"
services:
@@ -73,32 +99,24 @@ services:
- floci
```
-1. Must match the Compose service name so other containers can resolve it.
+1. Must match the Compose service name so other containers can resolve it by DNS.
-With this setting Floci returns URLs like
-`http://floci:4566/000000000000/my-queue` that other containers in the same
-network can reach.
+With this setting Floci returns URLs like `http://floci:4566/000000000000/my-queue` that other containers can reach.
-This is also the recommended setting when Floci launches Lambda containers into
-your Compose network via `FLOCI_SERVICES_LAMBDA_DOCKER_NETWORK` or
-`FLOCI_SERVICES_DOCKER_NETWORK`. It makes the endpoint Floci injects into
-Lambda containers, and response fields such as SQS `QueueUrl`, use a Docker
-service name (`floci`) instead of a host-only `localhost` address.
+This also ensures that Lambda containers Floci spawns into your Compose network receive a reachable endpoint, and that response fields such as SQS `QueueUrl` use the Docker service name instead of `localhost`.
-This affects any response field that embeds the endpoint hostname:
+Fields affected:
- SQS — `QueueUrl`
-- SNS — `TopicArn` callback URLs and subscription `SubscriptionArn` endpoints
-- Any pre-signed URL or callback that is generated from `floci.base-url`
+- SNS — topic ARN callback URLs and subscription endpoints
+- Any pre-signed URL or callback generated from `FLOCI_BASE_URL`
!!! tip "CI pipelines"
- In GitHub Actions or GitLab CI where both your app and Floci run as
- `services`, set `FLOCI_HOSTNAME` to the service name (e.g. `floci`) and
- point your SDK at `http://floci:4566`.
+ In GitHub Actions or GitLab CI where both your app and Floci run as `services`, set `FLOCI_HOSTNAME` to the service name (e.g. `floci`) and point your SDK at `http://floci:4566`.
## Initialization Hooks
-Hook scripts can be mounted into the container to run custom setup and teardown logic at each lifecycle phase:
+Mount shell scripts into hook directories to run setup or teardown logic at each lifecycle phase. No configuration variable is needed — Floci detects scripts by directory:
```yaml title="docker-compose.yml"
services:
@@ -107,98 +125,22 @@ services:
ports:
- "4566:4566"
volumes:
- - ./init/boot.d:/etc/floci/init/boot.d:ro # before storage loads, no AWS APIs
+ - ./init/boot.d:/etc/floci/init/boot.d:ro # before storage loads — no AWS APIs yet
- ./init/start.d:/etc/floci/init/start.d:ro # after HTTP server is ready
- ./init/ready.d:/etc/floci/init/ready.d:ro # after all start hooks complete
- ./init/stop.d:/etc/floci/init/stop.d:ro # during shutdown, while HTTP is still up
```
-Phases you don't need can be omitted. Use the `latest-compat` image when your scripts call `aws` or `boto3` — it includes the AWS CLI and boto3 with the local endpoint pre-configured, so no `--endpoint-url` flag is needed.
+Use the `latest-compat` image when your scripts call `aws` or `boto3` — it includes the AWS CLI and boto3 pre-configured for the local endpoint, so no `--endpoint-url` flag is needed.
If you have existing LocalStack init scripts, mount them under the LocalStack-compat paths and they run unchanged:
-```yaml title="docker-compose.yml"
-volumes:
- - ./localstack-init/ready.d:/etc/localstack/init/ready.d:ro
-```
-
-See [Initialization Hooks](./initialization-hooks.md) for execution behavior, script types, and configuration details.
-
-## Persistence
-
-By default Floci stores all data in memory — data is lost on restart. To persist data to disk, set the storage path and enable persistent mode:
-
```yaml
-services:
- floci:
- image: floci/floci:latest
- ports:
- - "4566:4566"
- volumes:
- - ./data:/app/data
- environment:
- FLOCI_STORAGE_MODE: persistent
- FLOCI_STORAGE_PERSISTENT_PATH: /app/data
-```
-
-### Using Named Volumes
-
-Instead of bind-mounting a local directory, you can use Docker named volumes to keep your project directory clean:
-
-```yaml
-services:
- floci:
- image: floci/floci:latest
- ports:
- - "4566:4566"
- volumes:
- - floci-data:/app/data
- environment:
- FLOCI_STORAGE_MODE: persistent
- FLOCI_STORAGE_PERSISTENT_PATH: /app/data
-
volumes:
- floci-data:
+ - ./localstack-init/ready.d:/etc/localstack/init/ready.d:ro
```
-Named volumes are managed entirely by Docker and won't create files in your repository. This works with both the JVM and native images.
-
-## Docker Configuration
-
-For Docker daemon socket, private registry authentication, log rotation, and network settings see [Docker Configuration](./docker.md).
-
-## Environment Variables Reference
-
-All `application.yml` options can be overridden via environment variables using the `FLOCI_` prefix with underscores replacing dots and dashes:
-
-| Environment variable | Default | Description |
-|---|---|---|
-| `FLOCI_HOSTNAME` | _(none)_ | Hostname embedded in response URLs (SQS, SNS, pre-signed). Set to the Compose service name in multi-container setups |
-| `FLOCI_DEFAULT_REGION` | `us-east-1` | AWS region reported in ARNs |
-| `FLOCI_DEFAULT_ACCOUNT_ID` | `000000000000` | AWS account ID used in ARNs |
-| `FLOCI_STORAGE_MODE` | `memory` | Global storage mode (`memory`, `persistent`, `hybrid`, `wal`) |
-| `FLOCI_STORAGE_PERSISTENT_PATH` | `./data` | Directory for persistent storage |
-| `FLOCI_STORAGE_PRUNE_VOLUMES_ON_DELETE` | `false` | Remove named volumes immediately on resource delete (`true` in memory mode always) |
-| `FLOCI_STORAGE_HOST_PERSISTENT_PATH` | _(none)_ | Absolute host path for container bind mounts (RDS, OpenSearch, MSK, ECR). When unset, Floci uses named Docker volumes automatically. |
-| `FLOCI_DOCKER_DOCKER_HOST` | `unix:///var/run/docker.sock` | Docker daemon socket (shared by Lambda, RDS, ElastiCache) |
-| `FLOCI_DOCKER_DOCKER_CONFIG_PATH` | `` | Path to dir with Docker's config.json (e.g. `/root/.docker`) |
-| `FLOCI_DOCKER_REGISTRY_CREDENTIALS_0__SERVER` | `` | Registry hostname for explicit credential entry 0 |
-| `FLOCI_DOCKER_REGISTRY_CREDENTIALS_0__USERNAME` | `` | Username for explicit credential entry 0 |
-| `FLOCI_DOCKER_REGISTRY_CREDENTIALS_0__PASSWORD` | `` | Password for explicit credential entry 0 |
-| `FLOCI_SERVICES_LAMBDA_EPHEMERAL` | `false` | Remove Lambda containers after each invocation |
-| `FLOCI_SERVICES_LAMBDA_DEFAULT_MEMORY_MB` | `128` | Default Lambda memory allocation |
-| `FLOCI_SERVICES_LAMBDA_DEFAULT_TIMEOUT_SECONDS` | `3` | Default Lambda timeout |
-| `FLOCI_SERVICES_LAMBDA_CODE_PATH` | `./data/lambda-code` | Where Lambda ZIPs are stored |
-| `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 Redis/Valkey 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 image |
-| `FLOCI_SERVICES_RDS_DEFAULT_MYSQL_IMAGE` | `mysql:8.0` | Default MySQL image |
-| `FLOCI_SERVICES_RDS_DEFAULT_MARIADB_IMAGE` | `mariadb:11` | Default MariaDB image |
-| `FLOCI_SERVICES_DOCKER_NETWORK` | _(none)_ | Docker network to attach spawned containers |
-| `FLOCI_AUTH_VALIDATE_SIGNATURES` | `false` | Verify AWS request signatures |
+See [Initialization Hooks](./initialization-hooks.md) for execution order, script types, and exit-code behavior.
## CI Pipeline Example
@@ -218,3 +160,24 @@ steps:
AWS_SECRET_ACCESS_KEY: test
run: mvn test
```
+
+## Common Environment Variables
+
+The most frequently set variables when running Floci as a Docker image:
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `FLOCI_HOSTNAME` | _(none)_ | Hostname embedded in response URLs. Set to the Compose service name in multi-container setups |
+| `FLOCI_DEFAULT_REGION` | `us-east-1` | AWS region reported in ARNs and responses |
+| `FLOCI_DEFAULT_ACCOUNT_ID` | `000000000000` | AWS account ID used in ARNs |
+| `FLOCI_STORAGE_MODE` | `memory` | `memory`, `persistent`, `hybrid`, or `wal` |
+| `FLOCI_STORAGE_PERSISTENT_PATH` | `./data` | Directory for persistent storage |
+| `FLOCI_SERVICES_DOCKER_NETWORK` | _(none)_ | Docker network for spawned containers (Lambda, ElastiCache, RDS, OpenSearch, MSK) |
+| `FLOCI_AUTH_VALIDATE_SIGNATURES` | `false` | Verify AWS request signatures |
+| `FLOCI_SERVICES_LAMBDA_EPHEMERAL` | `false` | Remove Lambda containers after each invocation |
+
+For the complete list of every `FLOCI_*` variable, see [Environment Variables Reference](./environment-variables.md).
+
+## Docker Configuration
+
+For Docker daemon socket, private registry authentication, log rotation, and network settings see [Docker Configuration](./docker.md).
diff --git a/docs/configuration/environment-variables.md b/docs/configuration/environment-variables.md
new file mode 100644
index 0000000000..64dd4cfa02
--- /dev/null
+++ b/docs/configuration/environment-variables.md
@@ -0,0 +1,405 @@
+# Environment Variables Reference
+
+Floci is configured exclusively through environment variables. Every option below maps directly to a `FLOCI_*` variable — no YAML file is needed when running the published Docker image.
+
+---
+
+## Global
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_BASE_URL` | `http://localhost:4566` | Base URL embedded in response fields (SQS `QueueUrl`, pre-signed URLs, etc.) |
+| `FLOCI_HOSTNAME` | _(none)_ | Overrides only the hostname part of `FLOCI_BASE_URL`. Set to the Compose service name (e.g. `floci`) so other containers can reach Floci by DNS |
+| `FLOCI_DEFAULT_REGION` | `us-east-1` | AWS region used in ARNs and API responses |
+| `FLOCI_DEFAULT_ACCOUNT_ID` | `000000000000` | Fallback account ID used in ARNs when the request's access key is not exactly 12 digits. When the access key IS 12 digits, it is used directly as the account ID — see [Multi-Account Isolation](./multi-account.md) |
+| `FLOCI_DEFAULT_AVAILABILITY_ZONE` | `us-east-1a` | Availability zone reported in EC2 and other responses |
+| `FLOCI_MAX_REQUEST_SIZE` | `512` | Maximum HTTP request body size in megabytes |
+| `FLOCI_ECR_BASE_URI` | `public.ecr.aws` | Base URI for public ECR image references |
+
+---
+
+## Authentication
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_AUTH_VALIDATE_SIGNATURES` | `false` | When `true`, verifies AWS Signature V4 on every request. Leave `false` for local development |
+| `FLOCI_AUTH_PRESIGN_SECRET` | `local-emulator-secret` | Secret used to sign and verify pre-signed URLs |
+
+---
+
+## TLS / HTTPS
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_TLS_ENABLED` | `false` | Enable TLS/HTTPS on all endpoints (HTTP remains available simultaneously) |
+| `FLOCI_TLS_CERT_PATH` | _(none)_ | Path to a PEM certificate file. When set, disables auto-generation |
+| `FLOCI_TLS_KEY_PATH` | _(none)_ | Path to a PEM private key file. Required when `FLOCI_TLS_CERT_PATH` is set |
+| `FLOCI_TLS_SELF_SIGNED` | `true` | Auto-generate and persist a self-signed certificate when no cert/key paths are provided |
+
+See [TLS / HTTPS](./tls.md) for SDK configuration examples and WebSocket (`wss://`) support.
+
+---
+
+## Storage
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_STORAGE_MODE` | `memory` | Global storage backend: `memory`, `persistent`, `hybrid`, or `wal` |
+| `FLOCI_STORAGE_PERSISTENT_PATH` | `./data` | Container-side directory for persistent and hybrid storage |
+| `FLOCI_STORAGE_HOST_PERSISTENT_PATH` | `./data` | Host-side path for Docker volume bind-mounts (RDS, OpenSearch, MSK, ECR data). When unset, Floci uses named Docker volumes |
+| `FLOCI_STORAGE_PRUNE_VOLUMES_ON_DELETE` | `false` | Remove named Docker volumes immediately when the resource is deleted |
+| `FLOCI_STORAGE_WAL_COMPACTION_INTERVAL_MS` | `30000` | How often (ms) the WAL compaction runs. Only applies when `FLOCI_STORAGE_MODE=wal` |
+
+### Per-service storage overrides
+
+Each service can override the global storage mode and flush interval. Replace `<SERVICE>` with the uppercase service name:
+
+```
+FLOCI_STORAGE_SERVICES_<SERVICE>_MODE=hybrid
+FLOCI_STORAGE_SERVICES_<SERVICE>_FLUSH_INTERVAL_MS=5000
+```
+
+Available service names: `SSM`, `SQS`, `S3`, `DYNAMODB`, `SNS`, `LAMBDA`, `CLOUDWATCHLOGS`, `CLOUDWATCHMETRICS`, `SECRETSMANAGER`, `ACM`, `OPENSEARCH`, `RDS`, `ELASTICACHE`, `APPCONFIG`, `APPCONFIGDATA`, `BACKUP`.
+
+See [Storage Modes](./storage.md) for a full explanation of each mode.
+
+---
+
+## Docker Daemon
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_DOCKER_DOCKER_HOST` | `unix:///var/run/docker.sock` | Docker daemon socket path or TCP address |
+| `FLOCI_DOCKER_DOCKER_CONFIG_PATH` | _(none)_ | Path to a directory containing Docker's `config.json` for registry auth |
+| `FLOCI_DOCKER_LOG_MAX_SIZE` | `10m` | Log rotation max size for spawned containers (e.g. `10m`, `1g`) |
+| `FLOCI_DOCKER_LOG_MAX_FILE` | `3` | Number of rotated log files to keep for spawned containers |
+
+### Registry credentials
+
+Provide credentials for private registries (e.g. for Lambda base images). Use incrementing indexes (`0`, `1`, `2`, …) for multiple registries:
+
+| Variable | Description |
+|---|---|
+| `FLOCI_DOCKER_REGISTRY_CREDENTIALS_0__SERVER` | Registry hostname (e.g. `ghcr.io`) |
+| `FLOCI_DOCKER_REGISTRY_CREDENTIALS_0__USERNAME` | Registry username |
+| `FLOCI_DOCKER_REGISTRY_CREDENTIALS_0__PASSWORD` | Registry password or token |
+
+---
+
+## DNS
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_DNS_EXTRA_SUFFIXES` | _(none)_ | Comma-separated list of hostname suffixes that the embedded DNS server resolves to Floci's container IP. Useful when migrating from LocalStack: `FLOCI_DNS_EXTRA_SUFFIXES=localhost.localstack.cloud` |
+
+---
+
+## Initialization Hooks
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_INIT_HOOKS_SHELL_EXECUTABLE` | `/bin/sh` | Shell used to execute hook scripts |
+| `FLOCI_INIT_HOOKS_TIMEOUT_SECONDS` | `30` | Maximum time a single hook script may run |
+| `FLOCI_INIT_HOOKS_SHUTDOWN_GRACE_PERIOD_SECONDS` | `2` | Time allowed for stop hooks to complete during shutdown |
+
+See [Initialization Hooks](./initialization-hooks.md) for lifecycle phases and script conventions.
+
+---
+
+## Services — Shared
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_DOCKER_NETWORK` | _(none)_ | Docker network name used by all container-backed services (Lambda, RDS, ElastiCache, ECS, OpenSearch, EKS, MSK). Per-service overrides take precedence |
+
+---
+
+## Services — Core
+
+### SSM (Parameter Store)
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_SSM_ENABLED` | `true` | Enable the SSM service |
+| `FLOCI_SERVICES_SSM_MAX_PARAMETER_HISTORY` | `5` | Maximum number of historical versions kept per parameter |
+
+### SQS
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_SQS_ENABLED` | `true` | Enable the SQS service |
+| `FLOCI_SERVICES_SQS_DEFAULT_VISIBILITY_TIMEOUT` | `30` | Default message visibility timeout in seconds |
+| `FLOCI_SERVICES_SQS_MAX_MESSAGE_SIZE` | `262144` | Maximum message body size in bytes (256 KB) |
+| `FLOCI_SERVICES_SQS_CLEAR_FIFO_DEDUPLICATION_CACHE_ON_PURGE` | `false` | Reset the deduplication cache when a FIFO queue is purged |
+
+### SNS
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_SNS_ENABLED` | `true` | Enable the SNS service |
+
+### S3
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_S3_ENABLED` | `true` | Enable the S3 service |
+| `FLOCI_SERVICES_S3_DEFAULT_PRESIGN_EXPIRY_SECONDS` | `3600` | Default pre-signed URL expiry when none is specified |
+
+### DynamoDB
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_DYNAMODB_ENABLED` | `true` | Enable the DynamoDB service |
+
+### Lambda
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_LAMBDA_ENABLED` | `true` | Enable the Lambda service |
+| `FLOCI_SERVICES_LAMBDA_EPHEMERAL` | `false` | Remove Lambda containers immediately after each invocation |
+| `FLOCI_SERVICES_LAMBDA_DEFAULT_MEMORY_MB` | `128` | Default memory allocation for functions that don't specify one |
+| `FLOCI_SERVICES_LAMBDA_DEFAULT_TIMEOUT_SECONDS` | `3` | Default invocation timeout in seconds |
+| `FLOCI_SERVICES_LAMBDA_RUNTIME_API_BASE_PORT` | `9200` | First port in the Lambda Runtime API port range |
+| `FLOCI_SERVICES_LAMBDA_RUNTIME_API_MAX_PORT` | `9299` | Last port in the Lambda Runtime API port range |
+| `FLOCI_SERVICES_LAMBDA_CODE_PATH` | `./data/lambda-code` | Container path where Lambda deployment ZIPs are stored |
+| `FLOCI_SERVICES_LAMBDA_POLL_INTERVAL_MS` | `1000` | How often (ms) the SQS and Kinesis event source pollers check for new messages |
+| `FLOCI_SERVICES_LAMBDA_CONTAINER_IDLE_TIMEOUT_SECONDS` | `300` | Seconds of inactivity before an idle Lambda container is removed |
+| `FLOCI_SERVICES_LAMBDA_REGION_CONCURRENCY_LIMIT` | `1000` | Maximum concurrent Lambda invocations across all functions in a region |
+| `FLOCI_SERVICES_LAMBDA_UNRESERVED_CONCURRENCY_MIN` | `100` | Minimum unreserved concurrency pool |
+| `FLOCI_SERVICES_LAMBDA_HOT_RELOAD_ENABLED` | `false` | Watch Lambda code directories for changes and reload without redeployment |
+| `FLOCI_SERVICES_LAMBDA_HOT_RELOAD_ALLOWED_PATHS` | _(none)_ | Comma-separated host paths that hot-reload is allowed to watch |
+| `FLOCI_SERVICES_LAMBDA_DOCKER_NETWORK` | _(none)_ | Docker network for Lambda containers (overrides `FLOCI_SERVICES_DOCKER_NETWORK`) |
+| `FLOCI_SERVICES_LAMBDA_AWS_CONFIG_PATH` | _(none)_ | Host path bind-mounted read-only at `/opt/aws-config` inside Lambda containers for real credential discovery |
+
+### API Gateway
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_APIGATEWAY_ENABLED` | `true` | Enable the API Gateway v1 (REST) service |
+| `FLOCI_SERVICES_APIGATEWAYV2_ENABLED` | `true` | Enable the API Gateway v2 (HTTP + WebSocket) service |
+
+### IAM
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_IAM_ENABLED` | `true` | Enable the IAM service |
+| `FLOCI_SERVICES_IAM_ENFORCEMENT_ENABLED` | `false` | When `true`, enforce IAM policies on API calls. Leave `false` for most local development scenarios |
+
+### KMS
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_KMS_ENABLED` | `true` | Enable the KMS service |
+
+### Kinesis
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_KINESIS_ENABLED` | `true` | Enable the Kinesis Data Streams service |
+
+### Firehose
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_FIREHOSE_ENABLED` | `true` | Enable the Kinesis Data Firehose service |
+
+### EventBridge
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_EVENTBRIDGE_ENABLED` | `true` | Enable the EventBridge service |
+
+### Scheduler
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_SCHEDULER_ENABLED` | `true` | Enable the EventBridge Scheduler service |
+| `FLOCI_SERVICES_SCHEDULER_INVOCATION_ENABLED` | `true` | When `false`, schedules are stored but never invoked |
+| `FLOCI_SERVICES_SCHEDULER_TICK_INTERVAL_SECONDS` | `10` | How often (seconds) the scheduler checks for due schedules |
+
+### CloudWatch Logs
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_CLOUDWATCHLOGS_ENABLED` | `true` | Enable the CloudWatch Logs service |
+| `FLOCI_SERVICES_CLOUDWATCHLOGS_MAX_EVENTS_PER_QUERY` | `10000` | Maximum log events returned by a single `FilterLogEvents` call |
+
+### CloudWatch Metrics
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_CLOUDWATCHMETRICS_ENABLED` | `true` | Enable the CloudWatch Metrics service |
+
+### Secrets Manager
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_SECRETSMANAGER_ENABLED` | `true` | Enable the Secrets Manager service |
+| `FLOCI_SERVICES_SECRETSMANAGER_DEFAULT_RECOVERY_WINDOW_DAYS` | `30` | Default recovery window for deleted secrets |
+
+### Cognito
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_COGNITO_ENABLED` | `true` | Enable the Cognito User Pools service |
+
+### Step Functions
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_STEPFUNCTIONS_ENABLED` | `true` | Enable the Step Functions service |
+
+### CloudFormation
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_CLOUDFORMATION_ENABLED` | `true` | Enable the CloudFormation service |
+
+### ACM (Certificate Manager)
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_ACM_ENABLED` | `true` | Enable the ACM service |
+| `FLOCI_SERVICES_ACM_VALIDATION_WAIT_SECONDS` | `0` | Simulated delay before a requested certificate transitions to `ISSUED` |
+
+### SES (Simple Email Service)
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_SES_ENABLED` | `true` | Enable the SES service |
+| `FLOCI_SERVICES_SES_SMTP_HOST` | _(none)_ | SMTP relay host for outbound email. When unset, emails are captured in memory only |
+| `FLOCI_SERVICES_SES_SMTP_PORT` | `25` | SMTP relay port |
+| `FLOCI_SERVICES_SES_SMTP_USER` | _(none)_ | SMTP username |
+| `FLOCI_SERVICES_SES_SMTP_PASS` | _(none)_ | SMTP password |
+| `FLOCI_SERVICES_SES_SMTP_STARTTLS` | `DISABLED` | STARTTLS mode: `DISABLED`, `OPTIONAL`, or `REQUIRED` |
+
+### Pipes
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_PIPES_ENABLED` | `true` | Enable the EventBridge Pipes service |
+
+---
+
+## Services — Container-Backed
+
+These services spawn Docker containers. They require access to the Docker socket (`/var/run/docker.sock`).
+
+### ElastiCache
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_ELASTICACHE_ENABLED` | `true` | Enable the ElastiCache service |
+| `FLOCI_SERVICES_ELASTICACHE_PROXY_BASE_PORT` | `6379` | First port in the ElastiCache proxy range |
+| `FLOCI_SERVICES_ELASTICACHE_PROXY_MAX_PORT` | `6399` | Last port in the ElastiCache proxy range |
+| `FLOCI_SERVICES_ELASTICACHE_DEFAULT_IMAGE` | `valkey/valkey:8` | Default Docker image for cache clusters |
+| `FLOCI_SERVICES_ELASTICACHE_DOCKER_NETWORK` | _(none)_ | Docker network for ElastiCache containers (overrides `FLOCI_SERVICES_DOCKER_NETWORK`) |
+
+### RDS
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_RDS_ENABLED` | `true` | Enable the RDS service |
+| `FLOCI_SERVICES_RDS_PROXY_BASE_PORT` | `7001` | First port in the RDS proxy range |
+| `FLOCI_SERVICES_RDS_PROXY_MAX_PORT` | `7099` | Last port in the RDS proxy range |
+| `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_RDS_DOCKER_NETWORK` | _(none)_ | Docker network for RDS containers (overrides `FLOCI_SERVICES_DOCKER_NETWORK`) |
+
+### OpenSearch
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_OPENSEARCH_ENABLED` | `true` | Enable the OpenSearch service |
+| `FLOCI_SERVICES_OPENSEARCH_MOCK` | `false` | When `true`, domains are created instantly without a real container (API only) |
+| `FLOCI_SERVICES_OPENSEARCH_DEFAULT_IMAGE` | `opensearchproject/opensearch:2` | Docker image for OpenSearch domains |
+| `FLOCI_SERVICES_OPENSEARCH_PROXY_BASE_PORT` | `9400` | First port in the OpenSearch proxy range |
+| `FLOCI_SERVICES_OPENSEARCH_PROXY_MAX_PORT` | `9499` | Last port in the OpenSearch proxy range |
+| `FLOCI_SERVICES_OPENSEARCH_KEEP_RUNNING_ON_SHUTDOWN` | `false` | Keep OpenSearch containers running when Floci stops |
+
+### MSK (Managed Streaming for Kafka)
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_MSK_ENABLED` | `true` | Enable the MSK service |
+| `FLOCI_SERVICES_MSK_MOCK` | `false` | When `true`, clusters are created instantly without a real Redpanda container |
+| `FLOCI_SERVICES_MSK_DEFAULT_IMAGE` | `redpandadata/redpanda:latest` | Docker image for Kafka/Redpanda brokers |
+
+### ECR (Elastic Container Registry)
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_ECR_ENABLED` | `true` | Enable the ECR service |
+| `FLOCI_SERVICES_ECR_REGISTRY_IMAGE` | `registry:2` | Docker image for the ECR registry sidecar |
+| `FLOCI_SERVICES_ECR_REGISTRY_CONTAINER_NAME` | `floci-ecr-registry` | Name of the ECR registry sidecar container |
+| `FLOCI_SERVICES_ECR_REGISTRY_BASE_PORT` | `5100` | First port in the ECR registry range |
+| `FLOCI_SERVICES_ECR_REGISTRY_MAX_PORT` | `5199` | Last port in the ECR registry range |
+| `FLOCI_SERVICES_ECR_TLS_ENABLED` | `false` | Enable TLS for the ECR registry |
+| `FLOCI_SERVICES_ECR_KEEP_RUNNING_ON_SHUTDOWN` | `true` | Keep the ECR registry container running when Floci stops |
+| `FLOCI_SERVICES_ECR_URI_STYLE` | `hostname` | Repository URI style: `hostname` (`<account>.dkr.ecr.<region>.localhost`) or `path` |
+| `FLOCI_SERVICES_ECR_DOCKER_NETWORK` | _(none)_ | Docker network for the ECR registry container |
+
+### EKS (Elastic Kubernetes Service)
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_EKS_ENABLED` | `true` | Enable the EKS service |
+| `FLOCI_SERVICES_EKS_MOCK` | `false` | When `true`, clusters are created instantly without a real container |
+| `FLOCI_SERVICES_EKS_PROVIDER` | `k3s` | Kubernetes provider (`k3s`) |
+| `FLOCI_SERVICES_EKS_DEFAULT_IMAGE` | `rancher/k3s:latest` | Docker image for EKS clusters |
+| `FLOCI_SERVICES_EKS_API_SERVER_BASE_PORT` | `6500` | First port in the Kubernetes API server range |
+| `FLOCI_SERVICES_EKS_API_SERVER_MAX_PORT` | `6599` | Last port in the Kubernetes API server range |
+| `FLOCI_SERVICES_EKS_KEEP_RUNNING_ON_SHUTDOWN` | `false` | Keep EKS containers running when Floci stops |
+| `FLOCI_SERVICES_EKS_DOCKER_NETWORK` | _(none)_ | Docker network for EKS containers |
+
+### ECS (Elastic Container Service)
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_ECS_ENABLED` | `true` | Enable the ECS service |
+| `FLOCI_SERVICES_ECS_MOCK` | `false` | When `true`, tasks are registered but not actually run |
+| `FLOCI_SERVICES_ECS_DEFAULT_MEMORY_MB` | `512` | Default task memory when not specified in the task definition |
+| `FLOCI_SERVICES_ECS_DEFAULT_CPU_UNITS` | `256` | Default task CPU units when not specified in the task definition |
+| `FLOCI_SERVICES_ECS_DOCKER_NETWORK` | _(none)_ | Docker network for ECS task containers |
+
+### EC2
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_EC2_ENABLED` | `true` | Enable the EC2 service |
+| `FLOCI_SERVICES_EC2_MOCK` | `false` | When `true`, instances are registered in state but no containers are spawned |
+| `FLOCI_SERVICES_EC2_IMDS_PORT` | `9169` | Port for the EC2 Instance Metadata Service (IMDS) endpoint |
+| `FLOCI_SERVICES_EC2_SSH_PORT_RANGE_START` | `2200` | First port in the SSH port range for EC2 instances |
+| `FLOCI_SERVICES_EC2_SSH_PORT_RANGE_END` | `2299` | Last port in the SSH port range |
+
+### Athena
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_ATHENA_ENABLED` | `true` | Enable the Athena service |
+| `FLOCI_SERVICES_ATHENA_MOCK` | `false` | When `true`, queries are accepted but not executed |
+| `FLOCI_SERVICES_ATHENA_DEFAULT_IMAGE` | `floci/floci-duck:latest` | Docker image for the DuckDB query engine |
+| `FLOCI_SERVICES_ATHENA_DUCK_URL` | _(none)_ | URL of an existing DuckDB service. When set, Floci skips managing the container |
+
+---
+
+## Services — Additional
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_GLUE_ENABLED` | `true` | Enable the Glue service |
+| `FLOCI_SERVICES_BEDROCK_RUNTIME_ENABLED` | `true` | Enable the Bedrock Runtime service |
+| `FLOCI_SERVICES_TEXTRACT_ENABLED` | `true` | Enable the Textract service |
+| `FLOCI_SERVICES_TRANSFER_ENABLED` | `true` | Enable the Transfer Family service |
+| `FLOCI_SERVICES_ROUTE53_ENABLED` | `true` | Enable the Route 53 service |
+| `FLOCI_SERVICES_ELBV2_ENABLED` | `true` | Enable the ELBv2 (ALB/NLB) service |
+| `FLOCI_SERVICES_ELBV2_MOCK` | `false` | When `true`, load balancers are registered but no containers are spawned |
+| `FLOCI_SERVICES_AUTOSCALING_ENABLED` | `true` | Enable the Auto Scaling service |
+| `FLOCI_SERVICES_CODEBUILD_ENABLED` | `true` | Enable the CodeBuild service |
+| `FLOCI_SERVICES_CODEBUILD_DOCKER_NETWORK` | _(none)_ | Docker network for CodeBuild build containers |
+| `FLOCI_SERVICES_CODEDEPLOY_ENABLED` | `true` | Enable the CodeDeploy service |
+| `FLOCI_SERVICES_BACKUP_ENABLED` | `true` | Enable the AWS Backup service |
+| `FLOCI_SERVICES_BACKUP_JOB_COMPLETION_DELAY_SECONDS` | `3` | Simulated delay before backup jobs transition to `COMPLETED` |
+| `FLOCI_SERVICES_APPCONFIG_ENABLED` | `true` | Enable the AppConfig service |
+| `FLOCI_SERVICES_APPCONFIGDATA_ENABLED` | `true` | Enable the AppConfig Data service |
diff --git a/docs/configuration/initialization-hooks.md b/docs/configuration/initialization-hooks.md
index d00f74bb41..80c975d951 100644
--- a/docs/configuration/initialization-hooks.md
+++ b/docs/configuration/initialization-hooks.md
@@ -164,16 +164,22 @@ aws ssm delete-parameter --name /app/bootstrapped
## Configuration
-| Key | Default | Description |
+| Variable | Default | Description |
|---|---|---|
-| `floci.init-hooks.shell-executable` | `/bin/sh` | Shell used to run `.sh` scripts |
-| `floci.init-hooks.timeout-seconds` | `30` | Maximum runtime per script before it is killed and treated as a failure |
-| `floci.init-hooks.shutdown-grace-period-seconds` | `2` | Extra wait after terminating a timed-out process |
-
-```yaml title="application.yml"
-floci:
- init-hooks:
- shell-executable: /bin/sh
- timeout-seconds: 60
- shutdown-grace-period-seconds: 10
+| `FLOCI_INIT_HOOKS_SHELL_EXECUTABLE` | `/bin/sh` | Shell used to run `.sh` scripts |
+| `FLOCI_INIT_HOOKS_TIMEOUT_SECONDS` | `30` | Maximum runtime per script before it is killed and treated as a failure |
+| `FLOCI_INIT_HOOKS_SHUTDOWN_GRACE_PERIOD_SECONDS` | `2` | Extra wait after terminating a timed-out script |
+
+Example — extend the timeout for slow seed scripts:
+
+```bash
+FLOCI_INIT_HOOKS_TIMEOUT_SECONDS=120
+```
+
+Or in Docker Compose:
+
+```yaml
+environment:
+ FLOCI_INIT_HOOKS_TIMEOUT_SECONDS: "120"
+ FLOCI_INIT_HOOKS_SHELL_EXECUTABLE: /bin/bash
```
diff --git a/docs/configuration/multi-account.md b/docs/configuration/multi-account.md
new file mode 100644
index 0000000000..ebd23817ec
--- /dev/null
+++ b/docs/configuration/multi-account.md
@@ -0,0 +1,160 @@
+# Multi-Account Isolation
+
+Floci supports full per-account resource isolation out of the box. Resources created by one account are invisible to all others — no configuration flag required.
+
+## How It Works
+
+Every incoming request carries an AWS SigV4 `Authorization` header. Floci reads the **Access Key ID** (AKID) from that header and applies one simple rule:
+
+> **If the AKID is exactly 12 digits, it is used as the account ID.**
+> Any other key format (e.g. `AKIAIOSFODNN7EXAMPLE`) falls back to `FLOCI_DEFAULT_ACCOUNT_ID`.
+
+```
+Authorization: AWS4-HMAC-SHA256 Credential=111111111111/20260510/us-east-1/sqs/aws4_request, ...
+ ^^^^^^^^^^^^
+ 12-digit AKID → account ID 111111111111
+```
+
+Once the account ID is determined, every storage read and write is transparently namespaced under it. An SQS queue named `orders` created by account `111111111111` is stored and retrieved as `111111111111/orders` — completely separate from the same queue name under account `222222222222`.
+
+!!! note "Same convention as LocalStack"
+ This 12-digit AKID → account ID rule matches LocalStack's multi-account behavior, so existing multi-account test setups work without changes.
+
+## Default Behavior (Single Account)
+
+If you use any non-12-digit credentials (e.g. `test`, `AKIA…`), all requests resolve to the default account ID:
+
+```bash
+FLOCI_DEFAULT_ACCOUNT_ID=000000000000 # default
+```
+
+All ARNs and URLs use this value:
+
+```
+arn:aws:sqs:us-east-1:000000000000:my-queue
+http://localhost:4566/000000000000/my-queue
+```
+
+You can change the default account ID without enabling per-request isolation:
+
+```bash
+FLOCI_DEFAULT_ACCOUNT_ID=123456789012
+```
+
+## Enabling Multi-Account Isolation
+
+Use 12-digit numeric access key IDs. The secret access key can be any non-empty string — Floci does not validate signatures by default.
+
+### AWS CLI
+
+```bash
+# Configure two named profiles
+aws configure --profile account-a
+# AWS Access Key ID: 111111111111
+# AWS Secret Access Key: test
+
+aws configure --profile account-b
+# AWS Access Key ID: 222222222222
+# AWS Secret Access Key: test
+
+export AWS_ENDPOINT_URL=http://localhost:4566
+
+# Create the same queue name under both accounts
+aws sqs create-queue --queue-name orders --profile account-a
+aws sqs create-queue --queue-name orders --profile account-b
+
+# Each account sees only its own queue
+aws sqs list-queues --profile account-a # → .../111111111111/orders
+aws sqs list-queues --profile account-b # → .../222222222222/orders
+```
+
+### AWS SDK (Java)
+
+```java
+StaticCredentialsProvider accountA = StaticCredentialsProvider.create(
+ AwsBasicCredentials.create("111111111111", "test"));
+
+StaticCredentialsProvider accountB = StaticCredentialsProvider.create(
+ AwsBasicCredentials.create("222222222222", "test"));
+
+SqsClient clientA = SqsClient.builder()
+ .endpointOverride(URI.create("http://localhost:4566"))
+ .region(Region.US_EAST_1)
+ .credentialsProvider(accountA)
+ .build();
+
+SqsClient clientB = SqsClient.builder()
+ .endpointOverride(URI.create("http://localhost:4566"))
+ .region(Region.US_EAST_1)
+ .credentialsProvider(accountB)
+ .build();
+
+// Both calls succeed, resources are fully isolated
+clientA.createQueue(r -> r.queueName("orders"));
+clientB.createQueue(r -> r.queueName("orders"));
+```
+
+### AWS SDK (Python)
+
+```python
+import boto3
+
+def client(service, account_id):
+ return boto3.client(
+ service,
+ endpoint_url="http://localhost:4566",
+ region_name="us-east-1",
+ aws_access_key_id=account_id, # 12-digit → account ID
+ aws_secret_access_key="test",
+ )
+
+sqs_a = client("sqs", "111111111111")
+sqs_b = client("sqs", "222222222222")
+
+sqs_a.create_queue(QueueName="orders")
+sqs_b.create_queue(QueueName="orders")
+
+print(sqs_a.list_queues()["QueueUrls"]) # [".../111111111111/orders"]
+print(sqs_b.list_queues()["QueueUrls"]) # [".../222222222222/orders"]
+```
+
+## ARNs Include the Correct Account ID
+
+Floci embeds the resolved account ID in every ARN it generates:
+
+```
+arn:aws:sqs:us-east-1:111111111111:orders
+arn:aws:lambda:us-east-1:222222222222:function:my-fn
+arn:aws:s3:::my-bucket # S3 ARNs are account-agnostic
+```
+
+## Isolation Scope
+
+All services that use `StorageFactory` participate in account isolation automatically. This covers every service in Floci — SQS, SNS, S3, DynamoDB, Lambda, SSM, Secrets Manager, KMS, Kinesis, EventBridge, Cognito, RDS, ElastiCache, OpenSearch, MSK, and more.
+
+Background workers (Lambda event-source pollers, DynamoDB TTL sweeper, MSK readiness poller, OpenSearch readiness poller) iterate across all accounts internally and route writes back to the originating account. No cross-account data leaks through these async paths.
+
+## Signature Validation
+
+By default Floci **does not** validate SigV4 signatures — only the access key ID matters for account resolution. The secret access key can be any non-empty string.
+
+To enforce real signature validation:
+
+```bash
+FLOCI_AUTH_VALIDATE_SIGNATURES=true
+FLOCI_AUTH_PRESIGN_SECRET=your-secret # for pre-signed URL verification
+```
+
+When `validate-signatures` is `false` (the default), account isolation still works correctly — the AKID is extracted from the `Authorization` header regardless of whether the signature itself is verified.
+
+## Persistence and Account Isolation
+
+Storage keys are namespaced per account at the persistence layer. When using `persistent`, `hybrid`, or `wal` storage modes, each account's data is stored under its own key prefix. Restarting Floci restores each account's resources independently.
+
+## Configuration Reference
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_DEFAULT_ACCOUNT_ID` | `000000000000` | Account ID used when the AKID is not exactly 12 digits |
+| `FLOCI_DEFAULT_REGION` | `us-east-1` | Region used when not derivable from the `Authorization` header |
+| `FLOCI_AUTH_VALIDATE_SIGNATURES` | `false` | Enforce SigV4 signature verification |
diff --git a/docs/configuration/storage.md b/docs/configuration/storage.md
index 6b859ea423..fce4a1a009 100644
--- a/docs/configuration/storage.md
+++ b/docs/configuration/storage.md
@@ -13,61 +13,42 @@ Floci supports four storage backends. You can set a global default and override
## Global Configuration
-```yaml title="application.yml"
-floci:
- storage:
- mode: memory # shipped default (application.yml)
- persistent-path: ./data # base directory for all persistent data
- wal:
- compaction-interval-ms: 30000
-```
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_STORAGE_MODE` | `memory` | Storage backend (`memory`, `persistent`, `hybrid`, `wal`) |
+| `FLOCI_STORAGE_PERSISTENT_PATH` | `./data` | Base directory for all persistent data |
+| `FLOCI_STORAGE_WAL_COMPACTION_INTERVAL_MS` | `30000` | WAL compaction interval (milliseconds) |
!!! note "Code default vs shipped default"
- `EmulatorConfig.StorageConfig.mode` has a Java-level `@WithDefault("hybrid")`, but the shipped `src/main/resources/application.yml` overrides it to `memory`. Running the stock Docker image gives you `memory`; if you supply your own `application.yml` and omit `storage.mode`, you fall back to the code default `hybrid`.
+ The Java `@WithDefault` for `storage.mode` is `hybrid`, but the published Docker image ships with `memory` set in `application.yml`. Running the stock image gives you `memory` unless you set `FLOCI_STORAGE_MODE`.
## Per-Service Override
-When `mode` is omitted for a service, it inherits the global `storage.mode`. Only set a per-service mode when you need a different behaviour for that service.
-
-```yaml title="application.yml"
-floci:
- storage:
- mode: memory # default for all services
- services:
- dynamodb:
- mode: persistent # DynamoDB uses persistent; everything else uses memory
- flush-interval-ms: 5000
- s3:
- mode: hybrid # S3 uses hybrid; everything else uses memory
-```
-
-## Per-Service Storage Overrides
-
-Override the global mode for individual services via environment variables. When not set, the service inherits `FLOCI_STORAGE_MODE`.
-
-| Variable | Default | Description |
-|-----------------------------------------------------------------|----------------|----------------------------------------|
-| `FLOCI_STORAGE_SERVICES_SSM_MODE` | global default | SSM storage mode |
-| `FLOCI_STORAGE_SERVICES_SSM_FLUSH_INTERVAL_MS` | `5000` | SSM flush interval (ms) |
-| `FLOCI_STORAGE_SERVICES_SQS_MODE` | global default | SQS storage mode |
-| `FLOCI_STORAGE_SERVICES_S3_MODE` | global default | S3 storage mode |
-| `FLOCI_STORAGE_SERVICES_DYNAMODB_MODE` | global default | DynamoDB storage mode |
-| `FLOCI_STORAGE_SERVICES_DYNAMODB_FLUSH_INTERVAL_MS` | `5000` | DynamoDB flush interval (ms) |
-| `FLOCI_STORAGE_SERVICES_SNS_MODE` | global default | SNS storage mode |
-| `FLOCI_STORAGE_SERVICES_SNS_FLUSH_INTERVAL_MS` | `5000` | SNS flush interval (ms) |
-| `FLOCI_STORAGE_SERVICES_LAMBDA_MODE` | global default | Lambda storage mode |
-| `FLOCI_STORAGE_SERVICES_LAMBDA_FLUSH_INTERVAL_MS` | `5000` | Lambda flush interval (ms) |
-| `FLOCI_STORAGE_SERVICES_CLOUDWATCHLOGS_MODE` | global default | CloudWatch Logs storage mode |
-| `FLOCI_STORAGE_SERVICES_CLOUDWATCHLOGS_FLUSH_INTERVAL_MS` | `5000` | CloudWatch Logs flush interval (ms) |
-| `FLOCI_STORAGE_SERVICES_CLOUDWATCHMETRICS_MODE` | global default | CloudWatch Metrics storage mode |
-| `FLOCI_STORAGE_SERVICES_CLOUDWATCHMETRICS_FLUSH_INTERVAL_MS` | `5000` | CloudWatch Metrics flush interval (ms) |
-| `FLOCI_STORAGE_SERVICES_SECRETSMANAGER_MODE` | global default | Secrets Manager storage mode |
-| `FLOCI_STORAGE_SERVICES_SECRETSMANAGER_FLUSH_INTERVAL_MS` | `5000` | Secrets Manager flush interval (ms) |
-| `FLOCI_STORAGE_SERVICES_ACM_MODE` | global default | ACM storage mode |
-| `FLOCI_STORAGE_SERVICES_ACM_FLUSH_INTERVAL_MS` | `5000` | ACM flush interval (ms) |
-| `FLOCI_STORAGE_SERVICES_OPENSEARCH_MODE` | global default | OpenSearch storage mode |
-| `FLOCI_STORAGE_SERVICES_OPENSEARCH_FLUSH_INTERVAL_MS` | `5000` | OpenSearch flush interval (ms) |
-| `FLOCI_STORAGE_SERVICES_RDS_MODE` | global default | RDS storage mode (see note below) |
+When not set for a service, it inherits `FLOCI_STORAGE_MODE`. Only override when you need different behavior for a specific service.
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_STORAGE_SERVICES_SSM_MODE` | global default | SSM storage mode |
+| `FLOCI_STORAGE_SERVICES_SSM_FLUSH_INTERVAL_MS` | `5000` | SSM flush interval (ms) |
+| `FLOCI_STORAGE_SERVICES_SQS_MODE` | global default | SQS storage mode |
+| `FLOCI_STORAGE_SERVICES_S3_MODE` | global default | S3 storage mode |
+| `FLOCI_STORAGE_SERVICES_DYNAMODB_MODE` | global default | DynamoDB storage mode |
+| `FLOCI_STORAGE_SERVICES_DYNAMODB_FLUSH_INTERVAL_MS` | `5000` | DynamoDB flush interval (ms) |
+| `FLOCI_STORAGE_SERVICES_SNS_MODE` | global default | SNS storage mode |
+| `FLOCI_STORAGE_SERVICES_SNS_FLUSH_INTERVAL_MS` | `5000` | SNS flush interval (ms) |
+| `FLOCI_STORAGE_SERVICES_LAMBDA_MODE` | global default | Lambda storage mode |
+| `FLOCI_STORAGE_SERVICES_LAMBDA_FLUSH_INTERVAL_MS` | `5000` | Lambda flush interval (ms) |
+| `FLOCI_STORAGE_SERVICES_CLOUDWATCHLOGS_MODE` | global default | CloudWatch Logs storage mode |
+| `FLOCI_STORAGE_SERVICES_CLOUDWATCHLOGS_FLUSH_INTERVAL_MS` | `5000` | CloudWatch Logs flush interval (ms) |
+| `FLOCI_STORAGE_SERVICES_CLOUDWATCHMETRICS_MODE` | global default | CloudWatch Metrics storage mode |
+| `FLOCI_STORAGE_SERVICES_CLOUDWATCHMETRICS_FLUSH_INTERVAL_MS` | `5000` | CloudWatch Metrics flush interval (ms) |
+| `FLOCI_STORAGE_SERVICES_SECRETSMANAGER_MODE` | global default | Secrets Manager storage mode |
+| `FLOCI_STORAGE_SERVICES_SECRETSMANAGER_FLUSH_INTERVAL_MS` | `5000` | Secrets Manager flush interval (ms) |
+| `FLOCI_STORAGE_SERVICES_ACM_MODE` | global default | ACM storage mode |
+| `FLOCI_STORAGE_SERVICES_ACM_FLUSH_INTERVAL_MS` | `5000` | ACM flush interval (ms) |
+| `FLOCI_STORAGE_SERVICES_OPENSEARCH_MODE` | global default | OpenSearch storage mode |
+| `FLOCI_STORAGE_SERVICES_OPENSEARCH_FLUSH_INTERVAL_MS` | `5000` | OpenSearch flush interval (ms) |
+| `FLOCI_STORAGE_SERVICES_RDS_MODE` | global default | RDS metadata storage mode (see note below) |
!!! note "RDS storage mode"
`FLOCI_STORAGE_SERVICES_RDS_MODE` controls Floci's own metadata persistence for RDS, not the
@@ -76,6 +57,65 @@ Override the global mode for individual services via environment variables. When
instance is deleted. In other modes the volume is retained unless
`FLOCI_STORAGE_PRUNE_VOLUMES_ON_DELETE=true`.
+## Recommended Profiles
+
+=== "Fast CI"
+
+ All in memory — fastest possible startup and test execution:
+
+ ```bash
+ FLOCI_STORAGE_MODE=memory
+ ```
+
+=== "Local development"
+
+ Hybrid — survive restarts without slowing down writes:
+
+ ```bash
+ FLOCI_STORAGE_MODE=hybrid
+ FLOCI_STORAGE_PERSISTENT_PATH=/app/data
+ ```
+
+ Docker Compose:
+
+ ```yaml
+ volumes:
+ - floci-data:/app/data
+ environment:
+ FLOCI_STORAGE_MODE: hybrid
+ FLOCI_STORAGE_PERSISTENT_PATH: /app/data
+ ```
+
+=== "Durable development"
+
+ Persistent — every write is immediately on disk:
+
+ ```bash
+ FLOCI_STORAGE_MODE=persistent
+ FLOCI_STORAGE_PERSISTENT_PATH=/app/data
+ ```
+
+ Docker Compose:
+
+ ```yaml
+ volumes:
+ - floci-data:/app/data
+ environment:
+ FLOCI_STORAGE_MODE: persistent
+ FLOCI_STORAGE_PERSISTENT_PATH: /app/data
+ ```
+
+=== "Mixed"
+
+ Keep most services in memory, persist only DynamoDB and S3:
+
+ ```bash
+ FLOCI_STORAGE_MODE=memory
+ FLOCI_STORAGE_SERVICES_DYNAMODB_MODE=persistent
+ FLOCI_STORAGE_SERVICES_S3_MODE=hybrid
+ FLOCI_STORAGE_PERSISTENT_PATH=/app/data
+ ```
+
## Container Storage (RDS, OpenSearch, MSK, ECR)
Services that spawn Docker containers (RDS, OpenSearch, MSK, ECR registry) need a volume for their
@@ -108,7 +148,7 @@ docker volume prune --filter label=floci=true
By default volumes survive resource deletion, matching real AWS behavior.
-| `storage.mode` | Volume on resource delete |
+| `FLOCI_STORAGE_MODE` | Volume on resource delete |
|---|---|
| `memory` | **Always removed** — memory mode implies no persistence across restarts |
| `persistent` / `hybrid` / `wal` | Retained (default) — remove with `FLOCI_STORAGE_PRUNE_VOLUMES_ON_DELETE=true` |
@@ -132,44 +172,3 @@ FLOCI_STORAGE_HOST_PERSISTENT_PATH=/absolute/host/path/data
`FLOCI_STORAGE_HOST_PERSISTENT_PATH` must be an absolute path (starting with `/`). Volume
names and relative paths are not supported and will be silently ignored, falling back to
named-volume mode.
-
-## Environment Variable Override
-
-```bash
-FLOCI_STORAGE_MODE=persistent
-FLOCI_STORAGE_PERSISTENT_PATH=/app/data
-```
-
-## Recommended Profiles
-
-=== "Fast CI"
-
- All in memory, fastest possible startup and test execution:
-
- ```yaml
- floci:
- storage:
- mode: memory
- ```
-
-=== "Local development"
-
- Hybrid — survive restarts without slowing down writes:
-
- ```yaml
- floci:
- storage:
- mode: hybrid
- persistent-path: ./data
- ```
-
-=== "Durable development"
-
- Persistent — every write is immediately on disk:
-
- ```yaml
- floci:
- storage:
- mode: persistent
- persistent-path: ./data
- ```
\ No newline at end of file
diff --git a/docs/configuration/tls.md b/docs/configuration/tls.md
index 7b4082dd88..0a84155382 100644
--- a/docs/configuration/tls.md
+++ b/docs/configuration/tls.md
@@ -31,17 +31,6 @@ client = boto3.client('sts', endpoint_url='https://localhost:4566', verify=False
| `FLOCI_TLS_KEY_PATH` | *(unset)* | Path to PEM private key file |
| `FLOCI_TLS_SELF_SIGNED` | `true` | Auto-generate a self-signed certificate when no cert/key paths provided |
-### application.yml
-
-```yaml
-floci:
- tls:
- enabled: false
- # cert-path: "/path/to/cert.pem"
- # key-path: "/path/to/key.pem"
- self-signed: true
-```
-
## Self-Signed Certificate
When `FLOCI_TLS_ENABLED=true` and no custom certificate is provided, Floci auto-generates a self-signed certificate at startup. The certificate:
diff --git a/docs/getting-started/aws-setup.md b/docs/getting-started/aws-setup.md
index b8884cd167..5789d0b5e4 100644
--- a/docs/getting-started/aws-setup.md
+++ b/docs/getting-started/aws-setup.md
@@ -126,13 +126,19 @@ cfg, err := config.LoadDefaultConfig(context.TODO(),
)
```
-## Default Account ID
+## Account ID
-Floci uses account ID `000000000000` in all ARNs and queue URLs. For example:
+Floci uses account ID `000000000000` in all ARNs and queue URLs by default:
```
arn:aws:sqs:us-east-1:000000000000:my-queue
http://localhost:4566/000000000000/my-queue
```
-This can be changed via the `FLOCI_DEFAULT_ACCOUNT_ID` environment variable.
\ No newline at end of file
+Change the default with `FLOCI_DEFAULT_ACCOUNT_ID`:
+
+```bash
+FLOCI_DEFAULT_ACCOUNT_ID=123456789012
+```
+
+**Multi-account isolation** is also supported: if your access key ID is exactly 12 digits, Floci uses it directly as the account ID and fully isolates that account's resources from all others. See [Multi-Account Isolation](../configuration/multi-account.md) for details.
\ No newline at end of file
diff --git a/docs/getting-started/migrate-from-localstack.md b/docs/getting-started/migrate-from-localstack.md
index 7e5b08b064..1fff532c01 100644
--- a/docs/getting-started/migrate-from-localstack.md
+++ b/docs/getting-started/migrate-from-localstack.md
@@ -56,14 +56,19 @@ The port (`4566`), credentials (`test` / `test`), and AWS SDK configuration are
| `LOCALSTACK_HOST` | `FLOCI_HOSTNAME` | Hostname embedded in response URLs |
| `LOCALSTACK_HOSTNAME` | `FLOCI_HOSTNAME` | Alias — same effect |
| `PERSISTENCE=1` | `FLOCI_STORAGE_MODE=persistent` | Enable disk persistence |
+| `PERSIST_STATE=1` | `FLOCI_STORAGE_MODE=persistent` | Alias for `PERSISTENCE` — same effect |
| `EDGE_PORT` | `FLOCI_PORT` | Bind port override |
| `GATEWAY_LISTEN` | `QUARKUS_HTTP_HOST` | Bind address override |
| `LS_LOG` / `DEBUG=1` | `QUARKUS_LOG_LEVEL` | Log verbosity |
+| `DOCKER_HOST` | `FLOCI_DOCKER_DOCKER_HOST` | Docker daemon socket path or TCP address |
| `LAMBDA_DOCKER_NETWORK` | `FLOCI_SERVICES_LAMBDA_DOCKER_NETWORK` | Network for Lambda containers |
| `DOCKER_NETWORK` | `FLOCI_SERVICES_DOCKER_NETWORK` | Network for all spawned containers |
| `LAMBDA_REMOVE_CONTAINERS=1` | `FLOCI_SERVICES_LAMBDA_EPHEMERAL=true` | Remove Lambda containers after invocation |
+| `USE_SSL=1` | `FLOCI_TLS_ENABLED=true` | Enable TLS/HTTPS — see [TLS / HTTPS](../configuration/tls.md) |
+| `CUSTOM_SSL_CERT_PATH` | `FLOCI_TLS_CERT_PATH` + `FLOCI_TLS_KEY_PATH` | LocalStack accepts a single combined PEM; Floci accepts it in both fields |
| `SERVICES` | _(not needed)_ | Floci starts all 41 services instantly; no selection required |
| `LAMBDA_EXECUTOR` | _(not needed)_ | Floci always runs Lambda in Docker containers |
+| `LAMBDA_REMOTE_DOCKER` | _(not supported)_ | Use per-function `S3Bucket=hot-reload` instead — see [Lambda](../services/lambda.md) |
### 3 — Init scripts (no change required)
diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md
index f46cd2ea6b..0887fb31c6 100644
--- a/docs/getting-started/quick-start.md
+++ b/docs/getting-started/quick-start.md
@@ -208,5 +208,6 @@ sudo ufw allow in on docker0 to any port 5000:5099 proto tcp comment 'floci ecr
## Next Steps
- [Configure Docker Compose with ElastiCache and RDS ports](../configuration/docker-compose.md)
-- [Review all configuration options](../configuration/application-yml.md)
+- [Environment variables reference](../configuration/environment-variables.md)
+- [application.yml reference (source builds)](../configuration/advanced/application-yml.md)
- [Browse per-service documentation](../services/index.md)
diff --git a/docs/services/acm.md b/docs/services/acm.md
index ff6c1338b1..f8047c488d 100644
--- a/docs/services/acm.md
+++ b/docs/services/acm.md
@@ -28,6 +28,13 @@
- **Certificate Types:** `AMAZON_ISSUED` (default) and `PRIVATE` (when `CertificateAuthorityArn` is provided)
- **Export:** Only `PRIVATE` type certificates can be exported with their private key
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_ACM_ENABLED` | `true` | Enable or disable the service |
+| `FLOCI_SERVICES_ACM_VALIDATION_WAIT_SECONDS` | `0` | Seconds to wait before transitioning a certificate from `PENDING_VALIDATION` to `ISSUED` (0 = immediate) |
+
## Examples
```bash
diff --git a/docs/services/api-gateway.md b/docs/services/api-gateway.md
index c67ec334a2..180d6c1ee8 100644
--- a/docs/services/api-gateway.md
+++ b/docs/services/api-gateway.md
@@ -102,6 +102,13 @@ curl http://localhost:4566/restapis/$API_ID/dev/_user_request_/users
---
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_APIGATEWAY_ENABLED` | `true` | Enable or disable API Gateway v1 (REST APIs) |
+| `FLOCI_SERVICES_APIGATEWAYV2_ENABLED` | `true` | Enable or disable API Gateway v2 (HTTP and WebSocket APIs) |
+
## API Gateway v2 (HTTP and WebSocket APIs) {#v2}
**Protocol:** REST JSON
diff --git a/docs/services/appconfig.md b/docs/services/appconfig.md
index 7eb82a94eb..c54687c5c2 100644
--- a/docs/services/appconfig.md
+++ b/docs/services/appconfig.md
@@ -34,6 +34,13 @@ The data plane is used by applications to retrieve the active configuration for
- `StartConfigurationSession`
- `GetLatestConfiguration`
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_APPCONFIG_ENABLED` | `true` | Enable or disable the AppConfig management plane |
+| `FLOCI_SERVICES_APPCONFIGDATA_ENABLED` | `true` | Enable or disable the AppConfigData retrieval plane |
+
## Example Usage
### 1. Create an Application and Environment
diff --git a/docs/services/autoscaling.md b/docs/services/autoscaling.md
index 6a889ee2fa..fe0515631d 100644
--- a/docs/services/autoscaling.md
+++ b/docs/services/autoscaling.md
@@ -93,6 +93,12 @@ Floci runs a background reconciler (10 s fixed rate) that keeps each group's InS
- **Scale-in**: selects InService instances not protected from scale-in, deregisters them from target groups, then calls `TerminateInstances`.
- Activity records are written on each scale-out and scale-in event.
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_AUTOSCALING_ENABLED` | `true` | Enable or disable the service |
+
## Usage Example
```bash
diff --git a/docs/services/backup.md b/docs/services/backup.md
index ea0f78f47b..22ae143c99 100644
--- a/docs/services/backup.md
+++ b/docs/services/backup.md
@@ -80,11 +80,8 @@ When a job reaches `COMPLETED`:
The completion delay is configurable:
-```yaml
-floci:
- services:
- backup:
- job-completion-delay-seconds: 3 # default
+```bash
+FLOCI_SERVICES_BACKUP_JOB_COMPLETION_DELAY_SECONDS=3
```
Use a shorter delay (e.g. `1`) in test environments to speed up job-completion assertions.
diff --git a/docs/services/bedrock-runtime.md b/docs/services/bedrock-runtime.md
index 4feb79c6f0..bd1fdbd372 100644
--- a/docs/services/bedrock-runtime.md
+++ b/docs/services/bedrock-runtime.md
@@ -24,12 +24,9 @@ InvokeModel bodies are passed through as opaque bytes; the stub does not parse r
## Configuration
-```yaml
-floci:
- services:
- bedrock-runtime:
- enabled: true
-```
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_BEDROCKRUNTIME_ENABLED` | `true` | Enable or disable the service |
## Examples
diff --git a/docs/services/cloudformation.md b/docs/services/cloudformation.md
index c57c187c46..7097751477 100644
--- a/docs/services/cloudformation.md
+++ b/docs/services/cloudformation.md
@@ -83,6 +83,12 @@ All other resource types are accepted without error and assigned a synthetic phy
- Replacement-only changes such as `FunctionName` or `PackageType` changes create a replacement function and remove the old one.
- S3-backed code stays linked through `S3Bucket` / `S3Key`, so Lambda's reactive S3 sync continues to work for functions created by CloudFormation or CDK.
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_CLOUDFORMATION_ENABLED` | `true` | Enable or disable the service |
+
## Examples
```bash
diff --git a/docs/services/cloudwatch.md b/docs/services/cloudwatch.md
index 10d00bdb0c..e22e2bb748 100644
--- a/docs/services/cloudwatch.md
+++ b/docs/services/cloudwatch.md
@@ -30,13 +30,10 @@ Floci supports both CloudWatch Logs and CloudWatch Metrics.
### Configuration
-```yaml
-floci:
- services:
- cloudwatchlogs:
- enabled: true
- max-events-per-query: 10000
-```
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_CLOUDWATCHLOGS_ENABLED` | `true` | Enable or disable the CloudWatch Logs service |
+| `FLOCI_SERVICES_CLOUDWATCHLOGS_MAX_EVENTS_PER_QUERY` | `10000` | Maximum events returned per `FilterLogEvents` / `GetLogEvents` call |
### Examples
diff --git a/docs/services/codebuild.md b/docs/services/codebuild.md
index 3ad0c8ff39..c5edf0b8b4 100644
--- a/docs/services/codebuild.md
+++ b/docs/services/codebuild.md
@@ -86,12 +86,9 @@ When `artifacts.type=S3`, collected files are uploaded to the configured S3 buck
## Configuration
-```yaml
-floci:
- services:
- codebuild:
- enabled: true # default
-```
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_CODEBUILD_ENABLED` | `true` | Enable or disable the service |
## CLI Examples
diff --git a/docs/services/codedeploy.md b/docs/services/codedeploy.md
index 8cb765bb53..2bc5225a33 100644
--- a/docs/services/codedeploy.md
+++ b/docs/services/codedeploy.md
@@ -189,12 +189,9 @@ For `computePlatform: Lambda`, `CreateDeployment` performs real traffic shifting
## Configuration
-```yaml
-floci:
- services:
- codedeploy:
- enabled: true # default
-```
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_CODEDEPLOY_ENABLED` | `true` | Enable or disable the service |
## CLI Examples
diff --git a/docs/services/cognito.md b/docs/services/cognito.md
index a25d23596b..96355a44de 100644
--- a/docs/services/cognito.md
+++ b/docs/services/cognito.md
@@ -17,11 +17,11 @@ Standalone `TagResource` rejects reserved `floci:*` keys. `ListTagsForResource`
| **User Pool Tags** | TagResource, UntagResource, ListTagsForResource |
| **User Pool Clients** | CreateUserPoolClient, DescribeUserPoolClient, ListUserPoolClients, DeleteUserPoolClient |
| **Resource Servers** | CreateResourceServer, DescribeResourceServer, ListResourceServers, DeleteResourceServer |
-| **Admin User Management** | AdminCreateUser, AdminGetUser, AdminDeleteUser, AdminSetUserPassword, AdminUpdateUserAttributes |
+| **Admin User Management** | AdminCreateUser (including `MessageAction=RESEND`), AdminGetUser, AdminDeleteUser, AdminSetUserPassword, AdminUpdateUserAttributes |
| **User Operations** | SignUp, ConfirmSignUp, GetUser, UpdateUserAttributes, ChangePassword, ForgotPassword, ConfirmForgotPassword |
| **Authentication** | InitiateAuth, AdminInitiateAuth, RespondToAuthChallenge (supports USER_PASSWORD_AUTH, USER_SRP_AUTH, ADMIN_USER_SRP_AUTH) |
| **User Listing** | ListUsers |
-| **Groups** | CreateGroup, GetGroup, ListGroups, DeleteGroup, AdminAddUserToGroup, AdminRemoveUserFromGroup, AdminListGroupsForUser |
+| **Groups** | CreateGroup, GetGroup, UpdateGroup, ListGroups, ListUsersInGroup, DeleteGroup, AdminAddUserToGroup, AdminRemoveUserFromGroup, AdminListGroupsForUser |
## Well-Known And OAuth Endpoints
@@ -42,6 +42,12 @@ Standalone `TagResource` rejects reserved `floci:*` keys. `ListTagsForResource`
- It validates requested OAuth scopes against the app client's `AllowedOAuthScopes` and the pool's registered resource-server scopes.
- It advertises the prefixed token endpoint in `/{userPoolId}/.well-known/openid-configuration`.
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_COGNITO_ENABLED` | `true` | Enable or disable the service |
+
## Examples
```bash
diff --git a/docs/services/dynamodb.md b/docs/services/dynamodb.md
index 53343fd707..45dbed8d10 100644
--- a/docs/services/dynamodb.md
+++ b/docs/services/dynamodb.md
@@ -47,6 +47,14 @@ DynamoDB Streams are supported via a separate target (`DynamoDBStreams_20120810`
| `GetShardIterator` | Get a shard iterator |
| `GetRecords` | Read stream records from a shard |
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_DYNAMODB_ENABLED` | `true` | Enable or disable the service |
+| `FLOCI_STORAGE_SERVICES_DYNAMODB_MODE` | *(global default)* | Storage mode override for DynamoDB (`memory`, `persistent`, `hybrid`, `wal`) |
+| `FLOCI_STORAGE_SERVICES_DYNAMODB_FLUSH_INTERVAL_MS` | `5000` | Flush interval for `hybrid`/`wal` storage modes (milliseconds) |
+
## Examples
```bash
diff --git a/docs/services/ecr.md b/docs/services/ecr.md
index 50c7a40e0c..64bf4f1b50 100644
--- a/docs/services/ecr.md
+++ b/docs/services/ecr.md
@@ -39,33 +39,17 @@
## Configuration
-Defaults under `floci.services.ecr` in `application.yml`:
-
-```yaml
-floci:
- services:
- ecr:
- enabled: true
- registry-image: "registry:2"
- registry-container-name: floci-ecr-registry
- registry-base-port: 5100
- registry-max-port: 5199
- data-path: ./data/ecr
- tls-enabled: false
- keep-running-on-shutdown: true
- uri-style: hostname # or "path"
-```
-
-| Setting | Default | Description |
-| --- | --- | --- |
-| `enabled` | `true` | Enable the ECR control plane and lazy registry start |
-| `registry-image` | `registry:2` | Backing OCI registry image |
-| `registry-container-name` | `floci-ecr-registry` | Name used for idempotent reuse across restarts |
-| `registry-base-port` / `-max-port` | `5100` / `5199` | Port range allocated for the published registry port |
-| `data-path` | `./data/ecr` | Bind-mount root for `<data-path>/registry` (the registry's `/var/lib/registry`) |
-| `keep-running-on-shutdown` | `true` | Leave the container up so the next Floci start adopts it |
-| `uri-style` | `hostname` | `hostname` returns `*.dkr.ecr.<region>.localhost`; `path` returns `localhost:<port>/<account>/<region>/<repo>` |
-| `tls-enabled` | `false` | Reserved for the future ACM-backed TLS phase |
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_ECR_ENABLED` | `true` | Enable the ECR control plane and lazy registry start |
+| `FLOCI_SERVICES_ECR_REGISTRY_IMAGE` | `registry:2` | Backing OCI registry image |
+| `FLOCI_SERVICES_ECR_REGISTRY_CONTAINER_NAME` | `floci-ecr-registry` | Container name used for idempotent reuse across restarts |
+| `FLOCI_SERVICES_ECR_REGISTRY_BASE_PORT` | `5100` | First port in the registry port range |
+| `FLOCI_SERVICES_ECR_REGISTRY_MAX_PORT` | `5199` | Last port in the registry port range |
+| `FLOCI_SERVICES_ECR_DATA_PATH` | `./data/ecr` | Bind-mount root for the registry data directory |
+| `FLOCI_SERVICES_ECR_KEEP_RUNNING_ON_SHUTDOWN` | `true` | Leave the registry container running so the next Floci start adopts it |
+| `FLOCI_SERVICES_ECR_URI_STYLE` | `hostname` | `hostname` = `*.dkr.ecr.<region>.localhost`; `path` = `localhost:<port>/<account>/<region>/<repo>` |
+| `FLOCI_SERVICES_ECR_TLS_ENABLED` | `false` | Reserved for future ACM-backed TLS |
### Docker Compose port mapping
diff --git a/docs/services/ecs.md b/docs/services/ecs.md
index 640c6ba84c..e275869cfb 100644
--- a/docs/services/ecs.md
+++ b/docs/services/ecs.md
@@ -122,19 +122,6 @@ ECS emulates clusters, task definitions, tasks, and services. In the default con
## Configuration
-```yaml
-floci:
- services:
- ecs:
- enabled: true
- mock: false # Set true to skip Docker and run tasks as in-process stubs
- docker-network: "" # Docker network for task containers
- default-memory-mb: 512
- default-cpu-units: 256
-```
-
-### Environment Variables
-
| Variable | Default | Description |
|---|---|---|
| `FLOCI_SERVICES_ECS_ENABLED` | `true` | Enable or disable the ECS service |
diff --git a/docs/services/eks.md b/docs/services/eks.md
index 4346b579e9..f5c76779d6 100644
--- a/docs/services/eks.md
+++ b/docs/services/eks.md
@@ -47,23 +47,6 @@ services:
## Configuration
-```yaml
-floci:
- services:
- eks:
- enabled: true
- mock: false # true = metadata only, no Docker
- provider: k3s # only k3s is supported
- default-image: "rancher/k3s:latest"
- api-server-base-port: 6500 # first port in the k3s API server range
- api-server-max-port: 6599
- data-path: ./data/eks # host bind-mount root for cluster data
- docker-network: "" # inherits floci.services.docker-network if unset
- keep-running-on-shutdown: false # leave k3s containers running after Floci stops
-```
-
-### Environment Variables
-
| Variable | Default | Description |
|---|---|---|
| `FLOCI_SERVICES_EKS_ENABLED` | `true` | Enable the EKS service |
diff --git a/docs/services/elasticache.md b/docs/services/elasticache.md
index 2610403107..3cf6f6335b 100644
--- a/docs/services/elasticache.md
+++ b/docs/services/elasticache.md
@@ -21,15 +21,12 @@ Floci manages real Valkey/Redis Docker containers and proxies TCP connections to
## Configuration
-```yaml
-floci:
- services:
- elasticache:
- enabled: true
- proxy-base-port: 6379
- proxy-max-port: 6399
- default-image: "valkey/valkey:8"
-```
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_ELASTICACHE_ENABLED` | `true` | Enable or disable the service |
+| `FLOCI_SERVICES_ELASTICACHE_PROXY_BASE_PORT` | `6379` | First host port in the ElastiCache proxy range |
+| `FLOCI_SERVICES_ELASTICACHE_PROXY_MAX_PORT` | `6399` | Last host port in the ElastiCache proxy range |
+| `FLOCI_SERVICES_ELASTICACHE_DEFAULT_IMAGE` | `valkey/valkey:8` | Docker image for Redis/Valkey containers |
### Docker Compose
diff --git a/docs/services/elb.md b/docs/services/elb.md
index 1e644f57fc..63f77b1473 100644
--- a/docs/services/elb.md
+++ b/docs/services/elb.md
@@ -107,13 +107,6 @@ aws elbv2 delete-target-group \
## Configuration
-```yaml
-floci:
- services:
- elbv2:
- enabled: true # default: true
-```
-
| Environment variable | Default | Description |
|---|---|---|
| `FLOCI_SERVICES_ELBV2_ENABLED` | `true` | Enable or disable the ELBv2 service |
diff --git a/docs/services/eventbridge.md b/docs/services/eventbridge.md
index cf568dff9b..f301d4d377 100644
--- a/docs/services/eventbridge.md
+++ b/docs/services/eventbridge.md
@@ -22,6 +22,12 @@
| `ListTargetsByRule` | List targets for a rule |
| `PutEvents` | Publish custom events to an event bus |
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_EVENTBRIDGE_ENABLED` | `true` | Enable or disable the service |
+
## Examples
```bash
diff --git a/docs/services/firehose.md b/docs/services/firehose.md
index 67d511ba81..e2d9575975 100644
--- a/docs/services/firehose.md
+++ b/docs/services/firehose.md
@@ -22,6 +22,12 @@ Floci emulates Amazon Data Firehose for streaming data ingestion and delivery to
2. **Automatic Flush**: Floci automatically flushes the buffer to S3 after every 5 records for immediate local feedback.
3. **Format**: Records are flushed as raw NDJSON (newline-delimited JSON) to the `floci-firehose-results` bucket.
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_FIREHOSE_ENABLED` | `true` | Enable or disable the service |
+
## Example
```bash
diff --git a/docs/services/glue.md b/docs/services/glue.md
index b4c33a532d..8f8699362a 100644
--- a/docs/services/glue.md
+++ b/docs/services/glue.md
@@ -26,6 +26,12 @@ Floci emulates the AWS Glue Data Catalog and Glue Schema Registry, allowing you
Supported schema formats are `AVRO`, `JSON`, and `PROTOBUF`. Compatibility modes are `NONE`, `DISABLED`, `BACKWARD`, `BACKWARD_ALL`, `FORWARD`, `FORWARD_ALL`, `FULL`, and `FULL_ALL`.
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_GLUE_ENABLED` | `true` | Enable or disable the service |
+
## Integration with Athena
The Glue Data Catalog is automatically used by **Athena** to resolve table names to S3 locations and formats. When you submit an Athena query, Floci reads all Glue tables for the target database and generates DuckDB views on top of the underlying S3 objects before executing the SQL.
diff --git a/docs/services/iam.md b/docs/services/iam.md
index 5642bfeb5e..64cd338597 100644
--- a/docs/services/iam.md
+++ b/docs/services/iam.md
@@ -69,12 +69,10 @@ Setting `enforcement-enabled: true` activates the policy evaluator as a JAX-RS r
FLOCI_SERVICES_IAM_ENFORCEMENT_ENABLED=true
```
-**application.yml:**
+Docker Compose:
```yaml
-floci:
- services:
- iam:
- enforcement-enabled: true
+environment:
+ FLOCI_SERVICES_IAM_ENFORCEMENT_ENABLED: "true"
```
### Evaluation rules
@@ -146,6 +144,13 @@ AWS_ACCESS_KEY_ID=$AKID AWS_SECRET_ACCESS_KEY=$SECRET \
aws s3 ls
```
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_IAM_ENABLED` | `true` | Enable or disable the service |
+| `FLOCI_SERVICES_IAM_ENFORCEMENT_ENABLED` | `false` | Enforce IAM policies on all inbound requests |
+
## Examples
```bash
diff --git a/docs/services/kinesis.md b/docs/services/kinesis.md
index 03c9f71c7d..2031b759b6 100644
--- a/docs/services/kinesis.md
+++ b/docs/services/kinesis.md
@@ -43,6 +43,12 @@ aws kinesis describe-stream --stream-name events --endpoint-url $AWS_ENDPOINT_UR
aws kinesis describe-stream --stream-arn arn:aws:kinesis:us-east-1:000000000000:stream/events --endpoint-url $AWS_ENDPOINT_URL
```
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_KINESIS_ENABLED` | `true` | Enable or disable the service |
+
## Examples
## Enhanced Fan-Out (EFO)
diff --git a/docs/services/kms.md b/docs/services/kms.md
index 6956e530ea..cef4017675 100644
--- a/docs/services/kms.md
+++ b/docs/services/kms.md
@@ -31,6 +31,12 @@
| `EnableKeyRotation` | Enable automatic key rotation (symmetric keys only) |
| `DisableKeyRotation` | Disable automatic key rotation |
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_KMS_ENABLED` | `true` | Enable or disable the service |
+
## Examples
```bash
diff --git a/docs/services/lambda.md b/docs/services/lambda.md
index 3a0b6e50b2..77f6de779e 100644
--- a/docs/services/lambda.md
+++ b/docs/services/lambda.md
@@ -108,19 +108,6 @@ The `S3Key` must be an **absolute path** reachable by the Docker daemon. When Fl
Hot-reload must be enabled explicitly. By default it is disabled so that `S3Bucket=hot-reload` is treated as a regular S3 bucket name.
-```yaml
-floci:
- services:
- lambda:
- hot-reload:
- enabled: true # Required — off by default
- allowed-paths: # Optional allowlist; omit to allow any absolute path
- - /home/user/projects
- - /tmp
-```
-
-Via environment variables:
-
```bash
FLOCI_SERVICES_LAMBDA_HOT_RELOAD_ENABLED=true
@@ -192,26 +179,21 @@ These AWS Lambda operations have no handler in Floci. Calls will return `404` or
## Configuration
-```yaml
-floci:
- services:
- lambda:
- enabled: true
- ephemeral: false # Remove container after each invocation
- default-memory-mb: 128
- default-timeout-seconds: 3
- runtime-api-base-port: 9200
- runtime-api-max-port: 9299
- code-path: ./data/lambda-code # ZIP storage location
- poll-interval-ms: 1000
- container-idle-timeout-seconds: 300 # Idle container cleanup
- region-concurrency-limit: 1000 # Concurrent executions ceiling per region
- unreserved-concurrency-min: 100 # Min unreserved capacity PutFunctionConcurrency must leave
- hot-reload:
- enabled: false # true = enable bind-mount hot-reload via S3Bucket=hot-reload
- # allowed-paths: # Optional path allowlist (host paths that may be bind-mounted)
- # - /home/user/projects
-```
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_LAMBDA_ENABLED` | `true` | Enable or disable the service |
+| `FLOCI_SERVICES_LAMBDA_EPHEMERAL` | `false` | Remove containers after each invocation |
+| `FLOCI_SERVICES_LAMBDA_DEFAULT_MEMORY_MB` | `128` | Default function memory (MB) |
+| `FLOCI_SERVICES_LAMBDA_DEFAULT_TIMEOUT_SECONDS` | `3` | Default function timeout (seconds) |
+| `FLOCI_SERVICES_LAMBDA_RUNTIME_API_BASE_PORT` | `9200` | First port in the Lambda Runtime API range |
+| `FLOCI_SERVICES_LAMBDA_RUNTIME_API_MAX_PORT` | `9299` | Last port in the Lambda Runtime API range |
+| `FLOCI_SERVICES_LAMBDA_CODE_PATH` | `./data/lambda-code` | Directory where Lambda ZIP files are stored |
+| `FLOCI_SERVICES_LAMBDA_POLL_INTERVAL_MS` | `1000` | Event-source mapping poll interval (milliseconds) |
+| `FLOCI_SERVICES_LAMBDA_CONTAINER_IDLE_TIMEOUT_SECONDS` | `300` | Idle container shutdown timeout (seconds) |
+| `FLOCI_SERVICES_LAMBDA_REGION_CONCURRENCY_LIMIT` | `1000` | Maximum concurrent executions per region |
+| `FLOCI_SERVICES_LAMBDA_UNRESERVED_CONCURRENCY_MIN` | `100` | Minimum unreserved capacity `PutFunctionConcurrency` must leave |
+| `FLOCI_SERVICES_LAMBDA_HOT_RELOAD_ENABLED` | `false` | Enable bind-mount hot-reload via `S3Bucket=hot-reload` |
+| `FLOCI_SERVICES_LAMBDA_HOT_RELOAD_ALLOWED_PATHS` | *(unset)* | Comma-separated allowlist of host paths that may be bind-mounted |
### Docker socket requirement
@@ -270,13 +252,6 @@ If your Lambda functions have `AWS_ENDPOINT_URL=http://localhost.localstack.clou
hardcoded, add the LocalStack suffix to Floci's DNS resolver so it resolves to
Floci's IP without any function-side changes:
-```yaml
-floci:
- dns:
- extra-suffixes:
- - localhost.localstack.cloud
-```
-
Via environment variable — use a comma-separated list for multiple suffixes:
```bash
diff --git a/docs/services/msk.md b/docs/services/msk.md
index a0866abe26..4e02c7e711 100644
--- a/docs/services/msk.md
+++ b/docs/services/msk.md
@@ -20,14 +20,11 @@ Floci emulates Amazon MSK by orchestrating **Redpanda** containers. This provide
## Configuration
-```yaml
-floci:
- services:
- msk:
- enabled: true
- mock: false # Set to true for metadata-only CRUD (no Docker)
- default-image: "redpandadata/redpanda:latest"
-```
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_MSK_ENABLED` | `true` | Enable or disable the service |
+| `FLOCI_SERVICES_MSK_MOCK` | `false` | `true` = metadata-only CRUD, no Docker containers |
+| `FLOCI_SERVICES_MSK_DEFAULT_IMAGE` | `redpandadata/redpanda:latest` | Docker image for Redpanda (Kafka) containers |
## How it works
diff --git a/docs/services/opensearch.md b/docs/services/opensearch.md
index 2dc66d36a5..73c70a8fc3 100644
--- a/docs/services/opensearch.md
+++ b/docs/services/opensearch.md
@@ -79,27 +79,6 @@ services:
## Configuration
-```yaml title="application.yml"
-floci:
- services:
- opensearch:
- enabled: true
- mock: false # true = metadata only, no Docker
- default-image: "opensearchproject/opensearch:2"
- proxy-base-port: 9400 # port range for real-mode containers
- proxy-max-port: 9499
- keep-running-on-shutdown: false # leave containers running after Floci stops
- # data-path is derived from floci.storage.persistent-path/opensearch
- # docker network is shared with all other services via floci.services.docker-network
-
- storage:
- services:
- opensearch:
- flush-interval-ms: 5000 # flush interval when using hybrid/wal storage
-```
-
-### Environment Variables
-
| Variable | Default | Description |
|---|---|---|
| `FLOCI_SERVICES_OPENSEARCH_ENABLED` | `true` | Enable/disable the service |
diff --git a/docs/services/rds.md b/docs/services/rds.md
index 5a3e763f54..4b233d23cc 100644
--- a/docs/services/rds.md
+++ b/docs/services/rds.md
@@ -27,17 +27,14 @@ Floci manages real PostgreSQL, MySQL, and MariaDB Docker containers and proxies
## Configuration
-```yaml
-floci:
- services:
- 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"
-```
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_RDS_ENABLED` | `true` | Enable or disable the service |
+| `FLOCI_SERVICES_RDS_PROXY_BASE_PORT` | `7000` | First host port in the RDS proxy range |
+| `FLOCI_SERVICES_RDS_PROXY_MAX_PORT` | `7099` | Last host port in the RDS proxy range |
+| `FLOCI_SERVICES_RDS_DEFAULT_POSTGRES_IMAGE` | `postgres:16-alpine` | Docker image for PostgreSQL instances |
+| `FLOCI_SERVICES_RDS_DEFAULT_MYSQL_IMAGE` | `mysql:8.0` | Docker image for MySQL instances |
+| `FLOCI_SERVICES_RDS_DEFAULT_MARIADB_IMAGE` | `mariadb:11` | Docker image for MariaDB instances |
### Docker Compose
diff --git a/docs/services/route53.md b/docs/services/route53.md
index f5d9f16736..7964ae375c 100644
--- a/docs/services/route53.md
+++ b/docs/services/route53.md
@@ -48,16 +48,13 @@ ns-4.awsdns-04.co.uk
## Configuration
-```yaml
-floci:
- services:
- route53:
- enabled: true
- default-nameserver1: ns-1.awsdns-01.org
- default-nameserver2: ns-2.awsdns-02.net
- default-nameserver3: ns-3.awsdns-03.com
- default-nameserver4: ns-4.awsdns-04.co.uk
-```
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_ROUTE53_ENABLED` | `true` | Enable or disable the service |
+| `FLOCI_SERVICES_ROUTE53_DEFAULT_NAMESERVER1` | `ns-1.awsdns-01.org` | First default nameserver returned in delegation sets |
+| `FLOCI_SERVICES_ROUTE53_DEFAULT_NAMESERVER2` | `ns-2.awsdns-02.net` | Second default nameserver |
+| `FLOCI_SERVICES_ROUTE53_DEFAULT_NAMESERVER3` | `ns-3.awsdns-03.com` | Third default nameserver |
+| `FLOCI_SERVICES_ROUTE53_DEFAULT_NAMESERVER4` | `ns-4.awsdns-04.co.uk` | Fourth default nameserver |
## CLI Examples
diff --git a/docs/services/s3.md b/docs/services/s3.md
index 4b779f9387..84fbef6afc 100644
--- a/docs/services/s3.md
+++ b/docs/services/s3.md
@@ -40,15 +40,11 @@ These AWS S3 features have no handler in Floci. Calls will return an error (typi
## Configuration
-```yaml
-floci:
- services:
- s3:
- enabled: true
- default-presign-expiry-seconds: 3600
- auth:
- presign-secret: local-emulator-secret
-```
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_S3_ENABLED` | `true` | Enable or disable the service |
+| `FLOCI_SERVICES_S3_DEFAULT_PRESIGN_EXPIRY_SECONDS` | `3600` | Default pre-signed URL expiry (1 hour) |
+| `FLOCI_AUTH_PRESIGN_SECRET` | `local-emulator-secret` | Secret used to sign pre-signed URLs |
## Examples
diff --git a/docs/services/scheduler.md b/docs/services/scheduler.md
index 7b1984507a..3fbc662a37 100644
--- a/docs/services/scheduler.md
+++ b/docs/services/scheduler.md
@@ -37,6 +37,14 @@ window are skipped. The dispatcher ticks every
Supported target types: SQS, Lambda, SNS, EventBridge `PutEvents`.
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_SCHEDULER_ENABLED` | `true` | Enable or disable the service |
+| `FLOCI_SERVICES_SCHEDULER_INVOCATION_ENABLED` | `true` | Run the background dispatcher that fires scheduled targets (`false` = CRUD-only) |
+| `FLOCI_SERVICES_SCHEDULER_TICK_INTERVAL_SECONDS` | `10` | How often the dispatcher scans for due schedules (seconds) |
+
## Not Yet Supported
- `RetryPolicy` and `DeadLetterConfig` on failed invocations (stored but not honored)
diff --git a/docs/services/secrets-manager.md b/docs/services/secrets-manager.md
index b927709ddb..85793707d1 100644
--- a/docs/services/secrets-manager.md
+++ b/docs/services/secrets-manager.md
@@ -27,13 +27,10 @@
## Configuration
-```yaml
-floci:
- services:
- secretsmanager:
- enabled: true
- default-recovery-window-days: 30 # Days before a deleted secret is purged
-```
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_SECRETSMANAGER_ENABLED` | `true` | Enable or disable the service |
+| `FLOCI_SERVICES_SECRETSMANAGER_DEFAULT_RECOVERY_WINDOW_DAYS` | `30` | Days before a deleted secret is permanently purged |
## Examples
diff --git a/docs/services/ses.md b/docs/services/ses.md
index d0af55d420..eccec125c2 100644
--- a/docs/services/ses.md
+++ b/docs/services/ses.md
@@ -45,20 +45,6 @@ Floci exposes the classic Amazon SES Query API used by `aws ses ...` commands an
## Configuration
-```yaml
-floci:
- services:
- ses:
- enabled: true
- # smtp-host: mailpit # SMTP server for email relay (empty = store only)
- # smtp-port: 1025
- # smtp-user: ""
- # smtp-pass: ""
- # smtp-starttls: DISABLED # DISABLED, OPTIONAL, or REQUIRED
-```
-
-### Environment Variables
-
| Variable | Default | Description |
|---|---|---|
| `FLOCI_SERVICES_SES_ENABLED` | `true` | Enable or disable the SES service |
diff --git a/docs/services/sns.md b/docs/services/sns.md
index c6c10bde10..3f94bee76b 100644
--- a/docs/services/sns.md
+++ b/docs/services/sns.md
@@ -25,6 +25,14 @@
| `UntagResource` | Remove tags from a topic |
| `ListTagsForResource` | List tags on a topic |
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_SNS_ENABLED` | `true` | Enable or disable the service |
+| `FLOCI_STORAGE_SERVICES_SNS_MODE` | *(global default)* | Storage mode override for SNS (`memory`, `persistent`, `hybrid`, `wal`) |
+| `FLOCI_STORAGE_SERVICES_SNS_FLUSH_INTERVAL_MS` | `5000` | Flush interval for `hybrid`/`wal` storage modes (milliseconds) |
+
## Examples
```bash
diff --git a/docs/services/sqs.md b/docs/services/sqs.md
index 37e6c2543d..094a667df7 100644
--- a/docs/services/sqs.md
+++ b/docs/services/sqs.md
@@ -77,15 +77,12 @@ curl -X DELETE "http://localhost:4566/_aws/sqs/messages?QueueUrl=$QUEUE_URL"
## Configuration
-```yaml
-floci:
- services:
- sqs:
- enabled: true
- default-visibility-timeout: 30 # Seconds
- max-message-size: 262144 # 256 KB
- clear-fifo-deduplication-cache-on-purge: false # When true, PurgeQueue clears the FIFO deduplication cache for the queue and for any SNS FIFO topics that subscribe to that queue (SNS in-memory dedup)
-```
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_SQS_ENABLED` | `true` | Enable or disable the service |
+| `FLOCI_SERVICES_SQS_DEFAULT_VISIBILITY_TIMEOUT` | `30` | Default message visibility timeout (seconds) |
+| `FLOCI_SERVICES_SQS_MAX_MESSAGE_SIZE` | `262144` | Maximum message size in bytes (256 KB) |
+| `FLOCI_SERVICES_SQS_CLEAR_FIFO_DEDUPLICATION_CACHE_ON_PURGE` | `false` | When `true`, `PurgeQueue` also clears the FIFO deduplication cache for the queue and any SNS FIFO topics subscribed to it |
## Examples
diff --git a/docs/services/ssm.md b/docs/services/ssm.md
index ba227f2f09..f52cf0c884 100644
--- a/docs/services/ssm.md
+++ b/docs/services/ssm.md
@@ -22,18 +22,12 @@
## Configuration
-```yaml
-floci:
- services:
- ssm:
- enabled: true
- max-parameter-history: 5 # Versions retained per parameter
- storage:
- services:
- ssm:
- mode: memory
- flush-interval-ms: 5000
-```
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_SSM_ENABLED` | `true` | Enable or disable the service |
+| `FLOCI_SERVICES_SSM_MAX_PARAMETER_HISTORY` | `5` | Number of parameter versions retained per parameter |
+| `FLOCI_STORAGE_SERVICES_SSM_MODE` | *(global default)* | Storage mode override for SSM (`memory`, `persistent`, `hybrid`, `wal`) |
+| `FLOCI_STORAGE_SERVICES_SSM_FLUSH_INTERVAL_MS` | `5000` | Flush interval for `hybrid`/`wal` storage modes (milliseconds) |
## Examples
diff --git a/docs/services/step-functions.md b/docs/services/step-functions.md
index 2fc41936b6..6e8fddf8c7 100644
--- a/docs/services/step-functions.md
+++ b/docs/services/step-functions.md
@@ -20,6 +20,12 @@
| `SendTaskFailure` | Report task failure |
| `SendTaskHeartbeat` | Send a heartbeat for long-running tasks |
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_STEPFUNCTIONS_ENABLED` | `true` | Enable or disable the service |
+
## Examples
```bash
diff --git a/docs/services/sts.md b/docs/services/sts.md
index b57967319d..5b29c2ad58 100644
--- a/docs/services/sts.md
+++ b/docs/services/sts.md
@@ -14,6 +14,12 @@
| `GetFederationToken` | Get temporary credentials for a federated user |
| `DecodeAuthorizationMessage` | Decode an encoded authorization failure message |
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_STS_ENABLED` | `true` | Enable or disable the service |
+
## Examples
```bash
diff --git a/docs/services/textract.md b/docs/services/textract.md
index 2ce3f124f9..9dca335c85 100644
--- a/docs/services/textract.md
+++ b/docs/services/textract.md
@@ -36,12 +36,9 @@ Every block includes: `Id` (UUID), `Confidence` (99.9), `Page` (1), and a `Geome
## Configuration
-```yaml
-floci:
- services:
- textract:
- enabled: true
-```
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_TEXTRACT_ENABLED` | `true` | Enable or disable the service |
## Examples
diff --git a/docs/services/transfer.md b/docs/services/transfer.md
index c1cfa22158..4fbfd446c7 100644
--- a/docs/services/transfer.md
+++ b/docs/services/transfer.md
@@ -47,13 +47,6 @@ AWS Transfer Family managed file transfer server management. This implementation
## Configuration
-```yaml
-floci:
- services:
- transfer:
- enabled: true
-```
-
| Environment variable | Default | Description |
|---|---|---|
| `FLOCI_SERVICES_TRANSFER_ENABLED` | `true` | Enable or disable Transfer Family |
diff --git a/docs/testcontainers/go.md b/docs/testcontainers/go.md
index a53785878f..cf785a440d 100644
--- a/docs/testcontainers/go.md
+++ b/docs/testcontainers/go.md
@@ -1,14 +1,16 @@
# Testcontainers — Go
-!!! warning "In progress"
- Go support is under active development. Track the work at
- [github.com/floci-io/testcontainers-floci-go](https://github.com/floci-io/testcontainers-floci-go).
+The `testcontainers-floci-go` module integrates Floci with [Testcontainers for Go](https://golang.testcontainers.org/). It starts a real Floci container before your tests and shuts it down after, with no extra setup.
- The page below shows the planned API. Details may change before the first release.
+## Installation
-## Planned usage
+```bash
+go get github.com/floci-io/testcontainers-floci-go
+```
+
+Requires Go 1.25+ and Testcontainers for Go v0.42+.
-The module will follow the standard [Testcontainers for Go](https://golang.testcontainers.org/) patterns.
+## Basic usage
```go
package myservice_test
@@ -27,18 +29,18 @@ import (
func TestS3CreateBucket(t *testing.T) {
ctx := context.Background()
- container, err := floci.RunContainer(ctx)
+ container, err := floci.NewFlociContainer().Start(ctx)
if err != nil {
t.Fatal(err)
}
- defer container.Terminate(ctx)
+ defer container.Stop(ctx)
cfg, err := config.LoadDefaultConfig(ctx,
- config.WithRegion(container.Region()),
+ config.WithRegion(container.GetRegion()),
config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider(
- container.AccessKey(), container.SecretKey(), "",
+ container.GetAccessKey(), container.GetSecretKey(), "",
)),
- config.WithBaseEndpoint(container.Endpoint()),
+ config.WithBaseEndpoint(container.GetEndpoint()),
)
if err != nil {
t.Fatal(err)
@@ -60,7 +62,7 @@ func TestS3CreateBucket(t *testing.T) {
t.Fatal(err)
}
- found := false
+ var found bool
for _, b := range out.Buckets {
if aws.ToString(b.Name) == "my-bucket" {
found = true
@@ -73,7 +75,213 @@ func TestS3CreateBucket(t *testing.T) {
}
```
-## Contribute
+## SQS example
+
+```go
+func TestSqsSendReceive(t *testing.T) {
+ ctx := context.Background()
+
+ container, err := floci.NewFlociContainer().Start(ctx)
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer container.Stop(ctx)
+
+ cfg, _ := config.LoadDefaultConfig(ctx,
+ config.WithRegion(container.GetRegion()),
+ config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider(
+ container.GetAccessKey(), container.GetSecretKey(), "",
+ )),
+ config.WithBaseEndpoint(container.GetEndpoint()),
+ )
+
+ client := sqs.NewFromConfig(cfg)
+
+ queue, err := client.CreateQueue(ctx, &sqs.CreateQueueInput{
+ QueueName: aws.String("orders"),
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ _, err = client.SendMessage(ctx, &sqs.SendMessageInput{
+ QueueUrl: queue.QueueUrl,
+ MessageBody: aws.String(`{"event":"order.placed"}`),
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ out, err := client.ReceiveMessage(ctx, &sqs.ReceiveMessageInput{
+ QueueUrl: queue.QueueUrl,
+ MaxNumberOfMessages: 1,
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ if len(out.Messages) != 1 {
+ t.Fatalf("expected 1 message, got %d", len(out.Messages))
+ }
+}
+```
+
+## DynamoDB example
+
+```go
+func TestDynamoDBPutGet(t *testing.T) {
+ ctx := context.Background()
+
+ container, err := floci.NewFlociContainer().Start(ctx)
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer container.Stop(ctx)
+
+ cfg, _ := config.LoadDefaultConfig(ctx,
+ config.WithRegion(container.GetRegion()),
+ config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider(
+ container.GetAccessKey(), container.GetSecretKey(), "",
+ )),
+ config.WithBaseEndpoint(container.GetEndpoint()),
+ )
+
+ client := dynamodb.NewFromConfig(cfg)
+
+ _, err = client.CreateTable(ctx, &dynamodb.CreateTableInput{
+ TableName: aws.String("Orders"),
+ BillingMode: types.BillingModePayPerRequest,
+ AttributeDefinitions: []types.AttributeDefinition{
+ {AttributeName: aws.String("id"), AttributeType: types.ScalarAttributeTypeS},
+ },
+ KeySchema: []types.KeySchemaElement{
+ {AttributeName: aws.String("id"), KeyType: types.KeyTypeHash},
+ },
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ _, err = client.PutItem(ctx, &dynamodb.PutItemInput{
+ TableName: aws.String("Orders"),
+ Item: map[string]types.AttributeValue{
+ "id": &types.AttributeValueMemberS{Value: "order-1"},
+ "status": &types.AttributeValueMemberS{Value: "placed"},
+ },
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ result, err := client.GetItem(ctx, &dynamodb.GetItemInput{
+ TableName: aws.String("Orders"),
+ Key: map[string]types.AttributeValue{
+ "id": &types.AttributeValueMemberS{Value: "order-1"},
+ },
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ status := result.Item["status"].(*types.AttributeValueMemberS).Value
+ if status != "placed" {
+ t.Errorf("expected status 'placed', got '%s'", status)
+ }
+}
+```
+
+## Reusing the container across tests
+
+Start the container once with `TestMain` and share it across all tests in the package:
+
+```go
+var sharedContainer *floci.StartedFlociContainer
+
+func TestMain(m *testing.M) {
+ ctx := context.Background()
+
+ var err error
+ sharedContainer, err = floci.NewFlociContainer().Start(ctx)
+ if err != nil {
+ log.Fatalf("failed to start floci: %v", err)
+ }
+
+ code := m.Run()
+
+ sharedContainer.Stop(ctx)
+ os.Exit(code)
+}
+
+func awsCfg(ctx context.Context) aws.Config {
+ cfg, _ := config.LoadDefaultConfig(ctx,
+ config.WithRegion(sharedContainer.GetRegion()),
+ config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider(
+ sharedContainer.GetAccessKey(), sharedContainer.GetSecretKey(), "",
+ )),
+ config.WithBaseEndpoint(sharedContainer.GetEndpoint()),
+ )
+ return cfg
+}
+```
+
+## Options
+
+Options are chained on the builder before calling `Start`:
+
+```go
+container, err := floci.NewFlociContainer().
+ WithRegion("eu-west-1").
+ WithAccountID("123456789012").
+ WithImage("floci/floci:1.6.0").
+ WithDedicatedNetwork().
+ Start(ctx)
+```
+
+| Method | Default | Description |
+|---|---|---|
+| `WithImage(image string)` | `floci/floci:latest` | Docker image to use |
+| `WithRegion(region string)` | `us-east-1` | AWS region set in Floci and returned by `GetRegion()` |
+| `WithAccountID(id string)` | `000000000000` | Default AWS account ID used in ARNs |
+| `WithAvailabilityZone(az string)` | `us-east-1a` | Availability zone reported by Floci |
+| `WithDedicatedNetwork()` | _(none)_ | Create a dedicated Docker network for container-backed services (ElastiCache, RDS, OpenSearch, MSK) |
+
+## Service configuration
+
+Each service exposes a typed config struct. Pass it with the matching `With<Service>Config` method:
+
+```go
+container, err := floci.NewFlociContainer().
+ WithS3Config(floci.S3Config{
+ Enabled: true,
+ DefaultPresignExpirySeconds: 7200,
+ }).
+ WithSqsConfig(floci.SqsConfig{
+ Enabled: true,
+ DefaultVisibilityTimeout: 60,
+ MaxMessageSize: 131072,
+ }).
+ WithDynamoDbConfig(floci.DynamoDbConfig{
+ Enabled: true,
+ }).
+ Start(ctx)
+```
+
+Available config methods: `WithAcmConfig`, `WithApiGatewayConfig`, `WithAppConfigConfig`, `WithAthenaConfig`, `WithBackupConfig`, `WithBedrockRuntimeConfig`, `WithCloudFormationConfig`, `WithCloudWatchLogsConfig`, `WithCloudWatchMetricsConfig`, `WithCodeBuildConfig`, `WithCodeDeployConfig`, `WithCognitoConfig`, `WithDynamoDbConfig`, `WithEc2Config`, `WithEcrConfig`, `WithEcsConfig`, `WithEksConfig`, `WithElastiCacheConfig`, `WithElbConfig`, `WithEventBridgeConfig`, `WithFirehoseConfig`, `WithGlueConfig`, `WithIamConfig`, `WithKinesisConfig`, `WithKmsConfig`, `WithLambdaConfig`, `WithMskConfig`, `WithOpenSearchConfig`, `WithRdsConfig`, `WithRoute53Config`, `WithS3Config`, `WithSchedulerConfig`, `WithSecretsManagerConfig`, `WithSesConfig`, `WithSnsConfig`, `WithSqsConfig`, `WithSsmConfig`, `WithStepFunctionsConfig`, `WithStsConfig`, `WithTextractConfig`, `WithTransferConfig`.
+
+## `StartedFlociContainer` API
+
+| Method | Returns | Description |
+|---|---|---|
+| `GetEndpoint()` | `string` | Full HTTP endpoint, e.g. `http://localhost:32768` |
+| `GetRegion()` | `string` | AWS region configured at start |
+| `GetAccountID()` | `string` | AWS account ID configured at start |
+| `GetAccessKey()` | `string` | Always `"test"` |
+| `GetSecretKey()` | `string` | Always `"test"` |
+| `GetAvailabilityZone()` | `string` | Availability zone configured at start |
+| `GetDedicatedNetworkName()` | `string` | Docker network name, or empty string if not using a dedicated network |
+| `GetMappedPort(ctx, port int)` | `(int, error)` | Host port mapped to the given container port |
+| `Stop(ctx)` | `error` | Terminate the container and clean up |
+
+## Source
-If you would like to help build the Go module, open an issue or pull request at
-[github.com/floci-io/testcontainers-floci-go](https://github.com/floci-io/testcontainers-floci-go).
+[github.com/floci-io/testcontainers-floci-go](https://github.com/floci-io/testcontainers-floci-go)
diff --git a/mkdocs.yml b/mkdocs.yml
index 8533216e87..4dbf475ea2 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -61,13 +61,16 @@ nav:
- AWS CLI & SDK Setup: getting-started/aws-setup.md
- Migrate from LocalStack: getting-started/migrate-from-localstack.md
- Configuration:
+ - Environment Variables: configuration/environment-variables.md
- Docker Images: configuration/docker-images.md
- Docker Compose: configuration/docker-compose.md
- Ports Reference: configuration/ports.md
- - application.yml Reference: configuration/application-yml.md
+ - Multi-Account Isolation: configuration/multi-account.md
- Storage Modes: configuration/storage.md
- TLS / HTTPS: configuration/tls.md
- Initialization Hooks: configuration/initialization-hooks.md
+ - Advanced:
+ - application.yml Reference: configuration/advanced/application-yml.md
- Services:
- Overview: services/index.md
- SSM Parameter Store: services/ssm.md