Docker
Conectividad entre host, container y redes Docker.
Un puerto pertenece al proceso que escucha dentro del namespace de red del contenedor. documenta esa intención; publicar con crea una ruta desde una interfaz del host hacia el puerto interno.
EXPOSE-pcliente
→ host 127.0.0.1:8080
→ regla de publicación
→ container 172.x.x.x:3000
→ proceso escuchando en 0.0.0.0:3000Estas son fronteras distintas. Un puerto puede estar documentado pero no publicado; publicado pero sin proceso escuchando; o accesible desde otros containers sin aparecer en el host.
Una API Node.js:
server.listen(3000, '0.0.0.0');El 3000 es el puerto interno. 0.0.0.0 indica que escucha en todas las interfaces visibles dentro del namespace.
Si escucha en:
server.listen(3000, '127.0.0.1');solo acepta conexiones desde el loopback del mismo contenedor. Otro container o una regla de publicación puede llegar a la interfaz, pero el proceso no está enlazado allí.
EXPOSE 3000EXPOSE:
No:
Puede declararse:
EXPOSE 3000/tcp
EXPOSE 8125/udpdocker run -p 8080:3000 my-apiFormato:
[host_ip:]host_port:container_port[/protocol]Ejemplos:
docker run -p 127.0.0.1:8080:3000/tcp my-api
docker run -p 0.0.0.0:8080:3000 my-api
docker run -p '[::1]:8080:3000' my-apiLa sintaxis y soporte IPv6 dependen de plataforma y red. Verifica el resultado, no asumas equivalencia entre Linux y Docker Desktop.
docker run -p 127.0.0.1:5432:5432 postgres:17El puerto queda disponible para procesos del host, pero no se publica intencionalmente en interfaces externas. Sigue necesitando autenticación.
docker run -p 5432:5432 postgres:17Puede exponer PostgreSQL a la red. El alcance final depende de firewall, routing y plataforma.
Para una aplicación detrás de Nginx o Caddy:
internet
→ reverse proxy :443
→ API publicada solo en 127.0.0.1:3000No publiques directamente cada servicio si el proxy es el único punto de entrada.
Containers en la misma network no necesitan -p para comunicarse.
docker network create backend
docker run -d --network backend --name db postgres:17
docker run -d --network backend --name api my-apiLa API conecta a:
db:5432Publicar 5432 sería necesario solo si el host o un sistema externo debe acceder.
Dentro de la API:
localhost:5432significa “la API misma”, no el container de PostgreSQL ni el host.
Para otro container usa el nombre DNS del servicio. Para alcanzar el host, utiliza el mecanismo soportado por la plataforma y diseña esa dependencia explícitamente.
docker run -P my-api
docker port <container>-P publica los puertos expuestos en puertos disponibles del host.
Útil para:
La aplicación de prueba debe descubrir el puerto asignado, no asumir uno fijo.
También:
docker run -p 127.0.0.1::3000 my-apipuede solicitar un host port dinámico según soporte de la CLI.
Publicar TCP no publica UDP:
docker run \
-p 8080:8080/tcp \
-p 8080:8080/udp \
my-serviceProtocolos y healthchecks deben coincidir con el servicio real.
La implementación puede usar reglas de NAT, proxies de usuario u otros mecanismos según sistema, versión y configuración.
Conceptualmente:
packet llega al host
→ regla de forwarding
→ interface del container
→ socket del procesoNo dependas de manipular manualmente reglas internas creadas por Docker. Integra firewall y políticas de red mediante mecanismos soportados.
En macOS y Windows, los containers Linux viven en una VM. Docker Desktop reenvía puertos desde el host hacia esa VM y el container.
Consecuencias:
localhost del host puede ser reenviado por Desktop.Prueba en la plataforma objetivo.
services:
api:
image: my-api
ports:
- "127.0.0.1:3000:3000"
db:
image: postgres:17
expose:
- "5432"En Compose, expose documenta/acota puertos internos para el modelo, pero no publica al host. La network del proyecto ya permite comunicación entre servicios autorizados.
Publicar un puerto aumenta superficie:
Controles:
127.0.0.1 cuando corresponda;internet
→ proxy container :443 publicado
→ api:3000 interno
→ db:5432 internoCompose conceptual:
services:
proxy:
image: caddy
ports:
- "80:80"
- "443:443"
networks: [public, backend]
api:
image: my-api
networks: [backend, data]
db:
image: postgres:17
networks: [data]
networks:
public:
backend:
internal: true
data:
internal: trueSolo el proxy publica. La API y database usan DNS interno.
docker ps -a
docker logs apiDesde la app o una herramienta disponible:
docker exec api sh -c 'ss -lntp || netstat -lntp'Una image mínima puede no incluir estas herramientas. Usa debug container, logs o inspección del host.
127.0.0.1:3000 dentro del container no es igual a 0.0.0.0:3000.
docker port api
docker inspect api --format '{{json .NetworkSettings.Ports}}'curl -v http://127.0.0.1:8080/healthdocker run --rm --network backend curlimages/curl \
-v http://api:3000/healthDistingue DNS, timeout, connection refused y respuesta HTTP inválida.
La ruta llegó a un host/interfaz, pero no existe un proceso escuchando o la conexión fue rechazada.
Puede indicar firewall, routing, proceso bloqueado o destino inaccesible.
El nombre no se resolvió; revisa network compartida y aliases.
Revisa publicación, interfaz host y firewall.
Revisa DNS, network compartida y puerto interno. Los containers no deben conectarse al host port para hablar entre sí salvo diseño intencional.
Dos containers no pueden publicar normalmente el mismo IP:puerto simultáneamente.
Dockerfile expone 3000, pero PORT=4000. La metadata queda desalineada.
Revisa binding del proceso, daemon, network, DNS y firewall para ambas familias.
En plataformas compatibles, --network host comparte namespace de red y cambia el modelo de publicación. Reduce aislamiento y tiene diferencias de plataforma. No lo uses solo para evitar comprender -p.
UDP no tiene conexión equivalente a TCP; las herramientas y healthchecks deben ser apropiados.
Corrección: publicar con runtime cuando el host necesita acceso.
Corrección: nombre DNS en network compartida.
Corrección: network interna y acceso administrativo controlado.
Corrección: declarar alcance de exposición explícitamente.
Corrección: probar cada frontera: dentro, entre containers, host y exterior.
EXPOSE y -p cumplen funciones distintas.0.0.0.0 dentro del container permite escuchar en sus interfaces.localhost siempre depende del namespace desde el que se usa.EXPOSE 3000 no hace accesible una API desde el host.127.0.0.1:8080:3000 y 8080:3000?127.0.0.1 falla aunque exista -p?Volumes y persistencia, donde el estado se separa del lifecycle del container y aparecen responsabilidades de ownership, backup y restore.