The PaaS Image Contract

### What the platform is actually doing A managed container platform runs your image as a container and puts a router or load balancer in front of it. That router has to know one thing: which TCP port inside the container to connect to. Rather than reading it out of the image, essentially every such platform inverts the relationship -- it allocates the port itself and tells the container, at start time, through an environment variable. The near-universal name for that variable is `PORT`. The image's side of the contract is therefore: read `PORT` at startup, listen on it, and accept connections on the container's routable address. The reason platforms do it this way is that they are packing many containers onto shared hosts and reserving ports out of a pool; letting each image dictate its own port would produce collisions the platform cannot resolve. It also means the same image runs unchanged in every environment, which is the whole point of shipping an image as the deployable unit. ### Mistake one: the hardcoded port A Spring Boot photo-thumbnail service with `server.port: 8080` baked into `application.yml` starts perfectly, logs "Tomcat started on port 8080", and is then declared unhealthy by the platform, which was connecting to 43117. Nothing crashed -- the two sides simply never met. The fix is to let the injected value win: Spring Boot's relaxed binding already maps the environment variable `SERVER_PORT` onto `server.port`, so a platform that injects `PORT` needs that value forwarded, either by starting the JVM with `--server.port=${PORT}` or by setting `server.port: ${PORT:8080}` so the environment overrides a sane local default. ### Mistake two: the loopback bind This one is subtler because the process really is listening. Every container gets its own network namespace with its own loopback interface and its own `eth0`. Binding `127.0.0.1` binds that container's private loopback, which is not the same loopback as the host's and is not reachable from any other network namespace. A process in the container can curl itself and succeed; the platform's router cannot reach it at all. Binding `0.0.0.0` (or `::` for IPv6) means "every interface in this namespace", which includes the container's routable address, and that is what the platform needs. Frameworks differ in their defaults -- Spring Boot binds all interfaces unless you set `server.address`, while several development servers in other ecosystems default to localhost -- so this bites hardest when a team moves a dev-mode entrypoint into an image. The same failure shows up locally, which is how you can rehearse it. Publishing a port with `docker run -p 39001:43117` sets up forwarding from the host into the container's address on 43117; if the process bound only the container's loopback, the connection is accepted by the forwarder and then fails, and you see a connection error rather than a 404. Nothing about `-p` changes what the process bound. ### Why EXPOSE does not save you `EXPOSE 8080` in a Dockerfile is documentation recorded in the image's config. It publishes nothing, opens nothing, and cannot influence which address or port the process inside chooses. Its only mechanical effect is that `docker run -P` (capital P) publishes every exposed port to an ephemeral host port, and that some tooling reads it as a hint. Treating `EXPOSE` as the declaration of "the port my app serves on" is one of the most common junior misreadings of the Dockerfile. ### Writing it correctly Three properties make an image portable here. Read the port from the environment with a default, so the image also runs with a plain `docker run` and no variables set. Bind `0.0.0.0` explicitly rather than relying on a framework default you did not choose. And make sure the variable actually reaches the process: exec-form `ENTRYPOINT ["java", "-jar", "app.jar", "--server.port=${PORT}"]` does **not** expand `${PORT}`, because exec form does not invoke a shell -- the literal string `${PORT}` is passed as an argument. Either use a shell wrapper that `exec`s the real process (so it still becomes PID 1 and still receives signals), or let the framework read the environment variable itself and pass no port argument at all. ### How to diagnose it in ten seconds Get a shell in the container and look at what is listening. If the listening address is `127.0.0.1:43117` you have the bind bug; if it is `0.0.0.0:8080` when the platform injected 43117 you have the hardcoded-port bug; if nothing is listening at all the process failed to start and neither of these is your problem yet.