Docker published port connection refused: state, logs, mapping, then listener

Scope: a container was created or a port was published, but TCP connection is refused. Check in layers: container status, health, and exit reason; a bounded tail of recent logs; the actual docker port or compose port mapping; then the application's official health check from inside the container at the container port. If the internal check fails, repair application startup, readiness, or listen configuration. If it succeeds but host access fails, inspect publishing, host binding, and firewall scope.

In Compose, service-to-service traffic uses service-name:CONTAINER_PORT. localhost means the current container, and the host-published port is for host or external traffic. Match the right side of HOST_PORT:CONTAINER_PORT to the real internal listener.

Do not publish database or admin ports on every interface merely for diagnosis, and do not loop restarts until the causal logs disappear. Logs can contain tokens, DSNs, user paths, or private addresses; sanitize them before reporting an outcome. Supporting official page: https://docs.docker.com/compose/how-tos/networking/.