Skip to content

armgit / floci

Public Imported from GitHub
0

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.yml
index 63e112e0e1..9244a9d256 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -5,7 +5,6 @@ services:
dockerfile: Dockerfile
ports:
- "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_default
FLOCI_SERVICES_RDS_PROXY_BASE_PORT: "7001"
FLOCI_STORAGE_HOST_PERSISTENT_PATH: ${PWD}/data
+ FLOCI_HOSTNAME: floci
+ FLOCI_BASE_URL: http://floci:4566
networks:
floci_default:
aliases:
diff --git a/docs/configuration/docker-compose.md b/docs/configuration/docker-compose.md
index 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 networking
By default, Floci embeds `localhost` in response URLs — for example, SQS queue
diff --git a/docs/configuration/ports.md b/docs/configuration/ports.md
index 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
!!! note
When 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:
```yaml
services:
floci:
image: hectorvent/floci:latest
ports:
- - "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 file
diff --git a/docs/services/ecr.md b/docs/services/ecr.md
index 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
```bash
diff --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.java
index 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 endpoints
Map<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 port
var bindings = inspect.getNetworkSettings().getPorts().getBindings();
@@ -322,15 +345,27 @@ public class ContainerLifecycleManager {
// Fallback to container port
return 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 network
for (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.java
index 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();
}