Light, fluffy, and always free - The AWS Local Emulator alternative
docs: document FLOCI_HOSTNAME for multi-container Docker Compose setups (#224)
Hector Ventura538112716532
diff --git a/docs/configuration/application-yml.md b/docs/configuration/application-yml.mdindex 5c11455c01..e082789aef 100644--- a/docs/configuration/application-yml.md+++ b/docs/configuration/application-yml.md@@ -2,11 +2,37 @@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).+## 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```yamlfloci:base-url: "http://localhost:4566" # Used to build callback URLs (e.g. SNS subscription endpoints)+ hostname: "" # Override host in base-url for multi-container Docker setups (e.g. "floci")default-region: us-east-1default-account-id: "000000000000"max-request-size: 512 # Max HTTP request body size in MB (default 512 MB)diff --git a/docs/configuration/docker-compose.md b/docs/configuration/docker-compose.mdindex b4055c21c7..79ca0a95f5 100644--- a/docs/configuration/docker-compose.md+++ b/docs/configuration/docker-compose.md@@ -40,6 +40,50 @@ services:!!! 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.+## 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.++Set `FLOCI_HOSTNAME` to the Compose service name so that Floci uses that name+in every URL it generates:++```yaml title="docker-compose.yml"+services:+ floci:+ image: hectorvent/floci:latest+ ports:+ - "4566:4566"+ environment:+ FLOCI_HOSTNAME: floci # (1)++ app:+ build: .+ environment:+ AWS_ENDPOINT_URL: http://floci:4566+ depends_on:+ - floci+```++1. Must match the Compose service name so other containers can resolve it.++With this setting Floci returns URLs like+`http://floci:4566/000000000000/my-queue` that other containers in the same+network can reach.++This affects any response field that embeds the endpoint hostname:++- SQS — `QueueUrl`+- SNS — `TopicArn` callback URLs and subscription `SubscriptionArn` endpoints+- Any pre-signed URL or callback that is 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`.+## Initialization HooksHook scripts can be mounted into the container to run custom setup and teardown logic:@@ -102,6 +146,7 @@ All `application.yml` options can be overridden via environment variables using| 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`) |