Light, fluffy, and always free - The AWS Local Emulator alternative
fix(ecr): fixing port and network issues on ecr (#483)
Hector Venturae9f6417713b3
diff --git a/docker-compose.yml b/docker-compose.ymlindex 63e112e0e1..9244a9d256 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -5,7 +5,6 @@ services:dockerfile: Dockerfileports:- "4566:4566"- - "5100-5199:5100-5199"- "6379-6399:6379-6399"- "7001-7099:7001-7099"volumes:@@ -17,6 +16,8 @@ services:FLOCI_SERVICES_DOCKER_NETWORK: floci_defaultFLOCI_SERVICES_RDS_PROXY_BASE_PORT: "7001"FLOCI_STORAGE_HOST_PERSISTENT_PATH: ${PWD}/data+ FLOCI_HOSTNAME: floci+ FLOCI_BASE_URL: http://floci:4566networks:floci_default:aliases:diff --git a/docs/configuration/docker-compose.md b/docs/configuration/docker-compose.mdindex ae3e394b40..3c6715c3eb 100644--- a/docs/configuration/docker-compose.md+++ b/docs/configuration/docker-compose.md@@ -40,6 +40,9 @@ 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.+!!! 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.+## Multi-container networkingBy default, Floci embeds `localhost` in response URLs — for example, SQS queuediff --git a/docs/configuration/ports.md b/docs/configuration/ports.mdindex 2f989023d2..ca6806704e 100644--- a/docs/configuration/ports.md+++ b/docs/configuration/ports.md@@ -5,7 +5,7 @@| Port / Range | Protocol | Purpose ||---|---|---|| `4566` | HTTP | All AWS API calls (every service) |-| `5100–5199` | HTTP | ECR Registry port, for `docker push` / `docker pull` |+| `5100–5199` | HTTP | ECR Registry sidecar (`floci-ecr-registry`) — bound directly by that container, not the floci container || `6379–6399` | TCP | ElastiCache Redis proxy, one port per replication group || `7001–7099` | TCP | RDS proxy, one port per DB instance || `9200–9299` | HTTP | Lambda Runtime API (internal: consumed by spawned Lambda containers, not host-mapped) |@@ -75,19 +75,35 @@ This range is reserved for OpenSearch `mode: real`, which will spin up an OpenSe!!! noteWhen real mode lands, configure the range with `FLOCI_SERVICES_OPENSEARCH_PROXY_BASE_PORT` and `FLOCI_SERVICES_OPENSEARCH_PROXY_MAX_PORT`.+## Ports 5100–5199 — ECR Registry++ECR is backed by a separate `registry:2` sidecar container (`floci-ecr-registry`) that Floci starts lazily on the first ECR API call. That container binds its own host port directly — **do not** add `5100-5199` to the floci service's `ports` in Docker Compose. Doing so pre-allocates those ports on the floci container and prevents the sidecar from binding them, causing the ECR registry to fail to start.++```+host:5100 ←── floci-ecr-registry (registry:2 container, started by Floci)+ ↑+ EcrRegistryManager manages this container's lifecycle+```++`docker login localhost:5100` works because the sidecar has a direct host port binding. No docker-compose port mapping is needed.++!!! warning "Do not expose ECR port range on the floci service"+ Adding `- "5100-5199:5100-5199"` to the floci service ports will conflict with the ECR sidecar container and break `docker push` / `docker pull`.+## Exposing Ports in Docker Compose-When running Floci inside Docker, you must expose these ranges to the host so your application (or Redis/psql CLI) can connect:+When running Floci inside Docker, expose these ranges to the host so your application (or Redis/psql CLI) can connect. **ECR ports are excluded** — they are handled by the registry sidecar:```yamlservices:floci:image: hectorvent/floci:latestports:- - "4566:4566"- - "5100-5199:5100-5199"- - "6379-6399:6379-6399"- - "7001-7099:7001-7099"+ - "4566:4566" # All AWS API calls+ - "6379-6399:6379-6399" # ElastiCache / Redis proxy ports+ - "7001-7099:7001-7099" # RDS / PostgreSQL + MySQL proxy ports+ volumes:+ - /var/run/docker.sock:/var/run/docker.sock```If your application runs inside the same Docker Compose network, it can reach Floci directly on container port `4566` — the host port mapping is only needed for tools running on the host (CLI, IDE plugins, etc.).\ No newline at end of filediff --git a/docs/services/ecr.md b/docs/services/ecr.mdindex 8ba487c9ed..46d212630a 100644--- a/docs/services/ecr.md+++ b/docs/services/ecr.md@@ -67,6 +67,25 @@ floci:| `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 |+### Docker Compose port mapping++The ECR registry sidecar container binds its host port directly — do **not** add `5100-5199` to the floci service's `ports` in `docker-compose.yml`. Adding that range pre-allocates those ports on the floci container and prevents the sidecar from binding them:++```yaml+# Correct — no ECR port range on the floci service+services:+ floci:+ image: hectorvent/floci:latest+ ports:+ - "4566:4566"+ - "6379-6399:6379-6399" # ElastiCache+ - "7001-7099:7001-7099" # RDS+ volumes:+ - /var/run/docker.sock:/var/run/docker.sock+```++`docker login localhost:5100` works automatically once Floci starts the registry sidecar — no additional port mapping is needed.+## Examples```bashdiff --git a/src/main/java/io/github/hectorvent/floci/core/common/docker/ContainerLifecycleManager.java b/src/main/java/io/github/hectorvent/floci/core/common/docker/ContainerLifecycleManager.javaindex 26cf66bc47..6d5f6f2236 100644--- a/src/main/java/io/github/hectorvent/floci/core/common/docker/ContainerLifecycleManager.java+++ b/src/main/java/io/github/hectorvent/floci/core/common/docker/ContainerLifecycleManager.java@@ -95,6 +95,22 @@ public class ContainerLifecycleManager {dockerClient.startContainerCmd(containerId).exec();LOG.infov("Started container {0}", containerId);+ // For containers with port bindings, withNetworkMode was skipped during creation+ // (it suppresses port publishing on macOS Docker Desktop). Connect to the+ // configured network now, after the host port bindings are established.+ if (spec.networkMode() != null && !spec.networkMode().isBlank() && spec.hasPortBindings()) {+ try {+ dockerClient.connectToNetworkCmd()+ .withContainerId(containerId)+ .withNetworkId(spec.networkMode())+ .exec();+ LOG.debugv("Connected container {0} to network {1}", containerId, spec.networkMode());+ } catch (Exception e) {+ LOG.warnv("Could not connect container {0} to network {1}: {2}",+ containerId, spec.networkMode(), e.getMessage());+ }+ }+// Resolve endpointsMap<Integer, EndpointInfo> endpoints = resolveEndpoints(containerId, spec);@@ -266,8 +282,11 @@ public class ContainerLifecycleManager {hostConfig.withPortBindings(ports);}- // Network mode- if (spec.networkMode() != null && !spec.networkMode().isBlank()) {+ // Network mode: only set during creation when there are no host port bindings.+ // withNetworkMode() + port bindings suppresses port publishing on macOS Docker Desktop,+ // so containers with port bindings (e.g. ECR registry) connect to the network+ // after start via connectToNetworkCmd() instead.+ if (spec.networkMode() != null && !spec.networkMode().isBlank() && !spec.hasPortBindings()) {hostConfig.withNetworkMode(spec.networkMode());}@@ -303,13 +322,17 @@ public class ContainerLifecycleManager {Map<Integer, EndpointInfo> endpoints = new HashMap<>();for (int containerPort : spec.exposedPorts()) {- endpoints.put(containerPort, resolveEndpoint(inspect, containerPort));+ endpoints.put(containerPort, resolveEndpoint(inspect, containerPort, spec.networkMode()));}return endpoints;}private EndpointInfo resolveEndpoint(InspectContainerResponse inspect, int containerPort) {+ return resolveEndpoint(inspect, containerPort, null);+ }++ private EndpointInfo resolveEndpoint(InspectContainerResponse inspect, int containerPort, String preferredNetwork) {if (!containerDetector.isRunningInContainer()) {// Native mode: use localhost and the bound host portvar bindings = inspect.getNetworkSettings().getPorts().getBindings();@@ -322,15 +345,27 @@ public class ContainerLifecycleManager {// Fallback to container portreturn new EndpointInfo("localhost", containerPort);} else {- // Container mode: use container IP on the docker network- String containerIp = resolveContainerIp(inspect);+ // Container mode: use container IP on the docker network.+ // Prefer the configured network's IP — the container may be on multiple+ // networks (bridge + the configured network) when connectToNetworkCmd()+ // is used instead of withNetworkMode() during creation.+ String containerIp = resolveContainerIp(inspect, preferredNetwork);return new EndpointInfo(containerIp, containerPort);}}- private String resolveContainerIp(InspectContainerResponse inspect) {+ private String resolveContainerIp(InspectContainerResponse inspect, String preferredNetwork) {var networks = inspect.getNetworkSettings().getNetworks();if (networks != null) {+ // Prefer the configured network so that when the container is on both+ // bridge (default) and the service network, we return the right IP.+ if (preferredNetwork != null && networks.containsKey(preferredNetwork)) {+ String ip = networks.get(preferredNetwork).getIpAddress();+ if (ip != null && !ip.isBlank()) {+ return ip;+ }+ }+ // Fall back to any networkfor (Map.Entry<String, ContainerNetwork> entry : networks.entrySet()) {String ip = entry.getValue().getIpAddress();if (ip != null && !ip.isBlank()) {diff --git a/src/main/java/io/github/hectorvent/floci/services/ecr/registry/EcrRegistryManager.java b/src/main/java/io/github/hectorvent/floci/services/ecr/registry/EcrRegistryManager.javaindex 50e210b77a..467e0ea79d 100644--- a/src/main/java/io/github/hectorvent/floci/services/ecr/registry/EcrRegistryManager.java+++ b/src/main/java/io/github/hectorvent/floci/services/ecr/registry/EcrRegistryManager.java@@ -196,10 +196,15 @@ public class EcrRegistryManager {specBuilder.withBind(hostPersistentPath, internalMountPath);env.add("REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=" + internalMountPath + "/ecr/registry");} else {- // Host path bind-mount+ // Host path bind-mount.+ // normalize() eliminates any "./" segments produced by toAbsolutePath() on a+ // relative config path (e.g. "./data/ecr" → "/app/./data/ecr") so the+ // replace() matches reliably.String dataPath = Paths.get(config.services().ecr().dataPath(), "registry")- .toAbsolutePath().toString();- String hostDataPath = dataPath.replace(config.storage().persistentPath(), hostPersistentPath);+ .toAbsolutePath().normalize().toString();+ String persistentPath = Paths.get(config.storage().persistentPath())+ .toAbsolutePath().normalize().toString();+ String hostDataPath = dataPath.replace(persistentPath, hostPersistentPath);if (!inContainer) {ensureDataDir();}