16.4.2.4 Compose App Binding Issue

A Compose app binding issue is a specific, often confusing variant of the localhost-versus-all-interfaces binding problem, made more confusing in a Compose context because some diagnostic commands run from inside the same container as the application appear to succeed, masking the actual binding problem until it is tested from genuinely outside that single container's own network namespace.

Why an internal check can mislead

Running a connectivity test through docker compose exec executes inside the same container, and therefore the same network namespace, as the application itself, which means a connection to localhost succeeds even if the application is bound only to 127.0.0.1 and would be unreachable from anywhere else, including from a sibling service in the same Compose stack:

docker compose exec api curl http://localhost:3000/healthz

{"status":"ok"}

This success is genuinely true, but it confirms only that the application is reachable from within its own container; it provides no information at all about whether a sibling service, or the host itself through a published port, can reach it, which is exactly the distinction that matters when diagnosing a binding issue specifically.

The test that actually reveals the problem

Testing from a different service within the same Compose stack, rather than from within the affected service's own container, is what actually surfaces a binding-to-localhost-only problem:

docker compose exec worker curl http://api:3000/healthz

curl: (7) Failed to connect to api port 3000: Connection refused

A connection refused error here, despite the internal check from within api itself succeeding moments earlier, is the clear, specific signature of an application bound only to 127.0.0.1 rather than 0.0.0.0; the service name resolves correctly and the network path exists, but nothing is actually listening on an interface reachable from outside that one specific container.

Common frameworks defaulting to localhost-only binding

Many web framework development servers default to binding only to 127.0.0.1 specifically as a development-time safety default, intended to prevent accidental exposure on a developer's own machine, which becomes a problem the moment that same default is carried unchanged into a containerized environment where the whole point is being reachable from outside the container:

app.run(host="127.0.0.1", port=5000)

app.run(host="0.0.0.0", port=5000)

This specific default is extremely common across many frameworks' "quick start" examples and default scaffolding, which means it is a frequent, recurring cause of exactly this Compose-specific binding confusion whenever a project moves from "works great running directly on my machine" to "running inside a container as part of a Compose stack."

Verifying the actual listening address directly

Rather than relying on inference from connection behavior alone, directly checking what address the application process is actually bound to confirms the cause unambiguously:

docker compose exec api netstat -tlnp

tcp  127.0.0.1:3000  LISTEN

tcp  0.0.0.0:3000  LISTEN

The first output confirms the binding problem directly; the second confirms the application is correctly listening on all interfaces, in which case a connectivity failure from a sibling service has a different cause entirely, network attachment, naming, or port mismatch, rather than this specific binding issue.

Why this matters specifically for published ports too

The same binding restriction also affects whether a port published to the host actually works, since Docker's port publishing mechanism forwards traffic to the container's internal address, and if the application is listening only on 127.0.0.1 inside its own container, traffic forwarded from the host's published port mapping never reaches it either, since it arrives at the container's external-facing interface, not its loopback interface:

services:
  api:
    ports:
      - "3000:3000"

curl http://localhost:3000/healthz

curl: (56) Recv failure: Connection reset by peer

This confirms the binding issue affects host-level access through published ports in exactly the same way it affects sibling-service access, since both depend on the application actually listening on an interface other than its own loopback.

The fix, consistently applied

The fix is the same regardless of which symptom, sibling service unreachable or host-published port unreachable, surfaced the problem: configuring the application to listen on 0.0.0.0 (or, equivalently in many frameworks, an empty string or unspecified host value meaning all interfaces) rather than 127.0.0.1 specifically:

services:
  api:
    environment:
      - HOST=0.0.0.0

For frameworks where this is controlled by an environment variable rather than hardcoded in application source, exposing it as a configurable value through the Compose file's own environment section, defaulting appropriately for the containerized context, avoids needing to modify application source code at all for this specific, common adjustment.

Confirming the fix across both symptom paths

After applying the fix, verifying both the sibling-service connectivity and the host-published port access separately confirms the fix is complete, since fixing the binding correctly resolves both simultaneously but is worth confirming explicitly rather than assuming based on one check alone:

docker compose exec worker curl http://api:3000/healthz
curl http://localhost:3000/healthz

A successful result from both commands confirms the application is now genuinely listening on all interfaces rather than just its own loopback.

Common mistakes

• Testing connectivity only from within the affected service's own container, where a localhost-bound application appears to work correctly despite being unreachable from anywhere else.
• Carrying over a framework's development-time default of binding only to localhost without adjusting it for a containerized deployment context.
• Diagnosing a sibling-service connectivity failure as a networking or naming issue without first checking the target's actual listening address directly.
• Assuming a fix that resolves host-published port access automatically also resolves sibling-service access, or vice versa, without verifying both explicitly.
• Not exposing the application's listen address as a configurable value, making the fix harder to apply consistently across different deployment contexts without modifying source code.

A Compose app binding issue is distinguished from other connectivity problems by its specific, telling signature: an internal check from within the same container succeeds while every other path, sibling service or host-published port, fails identically, which together confirm the application is listening only on its own loopback interface rather than genuinely accepting connections from outside its own container.