Light, fluffy, and always free - The AWS Local Emulator alternative
docs(lambda): document Podman rootless support and Runtime API host override (#1340)
Hector Ventura3b4e73ca5a52
diff --git a/docs/configuration/docker.md b/docs/configuration/docker.mdindex 5d643878db..19caa1c086 100644--- a/docs/configuration/docker.md+++ b/docs/configuration/docker.md@@ -120,6 +120,52 @@ Individual services can override the network with their own `docker-network` set!!! tipIn Docker Compose, the default network name is `<project-name>_default`. If your compose file is in a directory named `myapp`, the network is `myapp_default`.+## Running on Podman (rootless)++Floci runs under rootless Podman, but Podman's network topology needs a few+explicit settings that Docker handles automatically. The following configuration+is known to work:++```bash+podman network create floci-net++podman run -d --name floci \+ --network floci-net \+ -p 4566:4566 \+ -v /run/user/$(id -u)/podman/podman.sock:/var/run/docker.sock:Z \+ -e FLOCI_SERVICES_LAMBDA_DOCKER_NETWORK=floci-net \+ -e FLOCI_HOSTNAME=floci \+ floci/floci+```++What each setting does and why it is needed:++- **Named network (`floci-net`)** — the rootless default bridge does not assign+ reachable IPs between containers, so spawned Lambda containers cannot reach+ Floci. Create a named network and put both Floci and its Lambda containers on it.+- **`FLOCI_SERVICES_LAMBDA_DOCKER_NETWORK=floci-net`** — makes Floci attach the+ Lambda containers it spawns to that same named network.+- **`FLOCI_HOSTNAME=floci`** — gives Floci a stable name that Lambda containers+ resolve when calling back to the Runtime API.+- **`:Z` on the socket mount** — relabels the Podman socket for SELinux. Without+ it, Floci fails to talk to the Podman socket and Lambda container creation+ errors with `java.io.IOException: Broken pipe`.++!!! tip "When the Runtime API address is still unreachable"+ On some Podman network topologies the auto-detected Runtime API address+ (the host/IP Lambda containers use to call back into Floci) is still wrong,+ and invocations fail with `connect ECONNREFUSED <ip>:9200`. Set the address+ explicitly to bypass auto-detection:++ ```bash+ FLOCI_SERVICES_LAMBDA_DOCKER_HOST_OVERRIDE=floci+ ```++ This forces every spawned Lambda container to reach the Runtime API at the+ given host (here the `FLOCI_HOSTNAME` value), skipping Floci's+ auto-detection entirely. See the [Lambda docs](../services/lambda.md#configuration)+ for details.+## Full Reference| Environment variable | Default | Description |diff --git a/docs/configuration/environment-variables.md b/docs/configuration/environment-variables.mdindex 84d1a758f8..f3a05dc89c 100644--- a/docs/configuration/environment-variables.md+++ b/docs/configuration/environment-variables.md@@ -185,6 +185,7 @@ See [Initialization Hooks](./initialization-hooks.md) for lifecycle phases and s| `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_DOCKER_HOST_OVERRIDE` | _(none)_ | Explicit host/IP Lambda containers use to reach the Runtime API, bypassing auto-detection (e.g. rootless Podman) || `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 Gatewaydiff --git a/docs/services/lambda.md b/docs/services/lambda.mdindex de024b33a8..838501c92e 100644--- a/docs/services/lambda.md+++ b/docs/services/lambda.md@@ -194,6 +194,29 @@ These AWS Lambda operations have no handler in Floci. Calls will return `404` or| `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 |+| `FLOCI_SERVICES_LAMBDA_DOCKER_NETWORK` | *(unset)* | Docker network to attach Lambda containers to (overrides `FLOCI_SERVICES_DOCKER_NETWORK`) |+| `FLOCI_SERVICES_LAMBDA_DOCKER_HOST_OVERRIDE` | *(unset)* | Explicit host/IP that spawned Lambda containers use to reach Floci's Runtime API, bypassing auto-detection |++### Runtime API host override++When a Lambda container starts, it calls back into Floci's Runtime API to fetch+events and post results. Floci auto-detects the address containers should use+for that callback (its own container IP on the shared network, or+`host.docker.internal` when running on the host). In most setups this is+correct and needs no configuration.++On unusual network topologies — for example rootless Podman — auto-detection+can pick an address the Lambda container cannot reach, and invocations fail with+`connect ECONNREFUSED <ip>:9200`. Set `FLOCI_SERVICES_LAMBDA_DOCKER_HOST_OVERRIDE`+to the host or IP that containers can actually reach Floci on, and Floci uses it+verbatim instead of auto-detecting:++```bash+FLOCI_SERVICES_LAMBDA_DOCKER_HOST_OVERRIDE=floci+```++See [Docker Configuration → Running on Podman (rootless)](../configuration/docker.md#running-on-podman-rootless)+for a full rootless Podman walkthrough.### Docker socket requirement