Docker Port Mapping Explainer

Parses [[hostIp:]hostPort:]containerPort[/protocol], the main subset of the grammar Docker uses for -p/--publish and Compose ports: short syntax, and expands ranges pairwise. A host range with one container port, such as 8000-9000:80, stays one binding and is rendered as a range in both Compose syntaxes, including published: "8000-9000" in long syntax. Docker chooses an available host port from that range at runtime. Host ports 0-65535 are accepted; host port 0 requests automatic allocation. Container targets must be 1-65535: go-connections/nat parses target 0, but the current Moby daemon rejects it in validatePortBindings(). A host range starting at 0 with a nonzero end is accepted by nat but rejected by the Moby allocator at runtime. The host IP must be a plain IPv4 or IPv6 literal: a zoned IPv6 address such as fe80::1%eth0 is rejected, as Docker's own parser rejects it. A binding with no host port or host port 0 publishes on an ephemeral host port Docker assigns at runtime. Publishing to 0.0.0.0 exposes the port on every network interface of the host, and on Linux, Docker inserts its own iptables DNAT/FORWARD rules to reach the container — those rules are evaluated before a host firewall that only filters the INPUT chain, so such a firewall does not block published ports by itself. The conflict report assumes Docker's default host binding configuration, where an omitted host IP means 0.0.0.0; a daemon or network configured with a different default binding address is not modeled. Binding the wildcard address (0.0.0.0, or no host IP at all) and a specific address to the same host port and protocol is a partial conflict: Docker's own port allocator and the order the two containers are created in determine whether the second one is refused, so 0.0.0.0:8080 created after 127.0.0.1:8080 does not necessarily fail the same way the reverse order does. This tool does not read Docker state or a Compose file; it only evaluates the specs you paste in. Ephemeral ports and dynamic host ranges are excluded from the fixed-port conflict report; range overlap, exhaustion, and allocation order require runtime state. Expansion is bounded for the browser: an expanded container range may cover at most 1024 ports (dynamic host ranges are not expanded), at most 200 short-syntax lines and 200 long-syntax entries are parsed, and at most 2048 bindings in total (short and long syntax combined, short syntax first) are rendered; Docker itself accepts wider ranges. Lines over 512 characters and long-syntax blocks over 32 lines are reported rather than parsed. The conflict report lists at most 200 conflicting pairs and states how many more exist.