Put Two Containers on One User-Defined Network

Two containers on the same user-defined network can reach each other by name. On Docker's default network they cannot. That one difference explains most "connection refused" and "bad address" errors between containers, and the fix is one command.

Create a network and start a server

A network created with docker network create is a user-defined bridge network. Start an nginx web server on it. There is no -p, because only your other containers need to reach it, not your browser.

docker network create tutnet
docker run -d --name tut-web --network tutnet nginx:1.30-alpine

Unable to find image
Status: Downloaded newer image for nginx:1.30-alpine

docker network create prints the network ID, and docker run -d prints the container ID.

Reach it by name from a second container

Start a short-lived container on the same network and call the server by its container name.

docker run --rm --network tutnet alpine:3.24 wget -qO- http://tut-web

<title>Welcome to nginx!</title>

tut-web is not a hostname on the internet. Docker's built-in DNS on the network turned it into the container's address. No IP address was typed, and that is good, because the IP changes each time the container is created. Ping works the same way.

docker run --rm --network tutnet alpine:3.24 ping -c 1 tut-web

PING tut-web (
1 packets transmitted, 1 packets received, 0% packet loss

The same call on the default network fails

Run the same command without --network. The container lands on the default bridge network, which has no name lookup.

docker run --rm alpine:3.24 wget -qO- http://tut-web

wget: bad address 'tut-web'

"Bad address" is the DNS lookup failing. The name exists, but only on tutnet. The two containers are not on the same network, so they cannot find each other. This is the check to make first when one container cannot reach another.

See who is on a network

docker network inspect tutnet --format "{{range .Containers}}{{.Name}}{{println}}{{end}}"

tut-web

The list shows only running containers that are connected. The short-lived client is gone, so only the server is listed.

Connect a running container

You do not need to recreate a container to move it. Start one on the default network, then connect it.

docker run -d --name tut-plain alpine:3.24 sleep 300
docker network connect tutnet tut-plain
docker exec tut-plain wget -qO- http://tut-web

<title>Welcome to nginx!</title>

docker network connect adds a second network to a running container. docker network disconnect removes one. To remove the network itself, first remove all the containers on it.

Three things to remember

1. Name lookup works on user-defined networks only. Create one for every project.
2. Use the container's own port, 80 here, not a published port. Published ports are for your computer. Between containers, the container port is the one that counts.
3. A published port such as -p 8080:80 is not needed for container-to-container traffic.

Related course: Docker for Beginners.