Skip to content

armgit / floci

Public Imported from GitHub
0

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.md
index 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
!!! tip
In 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.md
index 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 Gateway
diff --git a/docs/services/lambda.md b/docs/services/lambda.md
index 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