Skip to content

armgit / floci

Public Imported from GitHub
0

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.md
index 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
```yaml
floci:
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-1
default-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.md
index 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 Hooks
Hook 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`) |