You have had the same breakdown for four lessons and you now know exactly what causes it: nslookup aurora-db returns NXDOMAIN because the default bridge network has no internal DNS between containers. The connectivity is there —nc -zv 172.17.0.2 5432 answers succeeded—, but the API does not know its database's name.

This is the lesson that fixes it, and with two commands. But before writing them you are going to genuinely understand Docker's network model: why each container has its own localhost, what each of the built-in drivers does, how the default bridge differs from one you create yourself, and what the difference is —one that gets confused constantly— between publishing a port and two containers talking to each other. Then you will create aurora-net, move the three services inside, and run the curl you have been waiting for all course. And to finish, you will put aurora-web in front with Nginx as a reverse proxy, and open the complete bookshop in your browser.

1. Why containers cannot see each other
2. The built-in network drivers
3. The default bridge versus user-defined networks
4. The docker network commands
5. Port publishing, revisited
6. Hands-on: aurora-net and name resolution
7. The moment of truth: /books returns the eight books
8. aurora-web: Nginx as a reverse proxy
9. Connecting and disconnecting networks on the fly
10. Networking best practices

A container is not just an isolated process: it has its own network namespace. That means it exclusively owns its list of interfaces, its routing table, its firewall rules, its ports and —this is what confuses everybody— its own localhost.

Three different localhosts on the same machine. When server.js was trying to connect to localhost:5432 in module 2, it was asking for PostgreSQL inside its own container, where only node lives. Hence the ECONNREFUSED: somebody answered (the container itself) saying nobody is listening there.

Check it for yourself:

Each with its own IP, and on the API's localhost there is no database at all. The rule, in one line:

Inside a container, localhost always means "myself". To talk to another container you have to use its address: its IP or, much better, its name.

Docker implements networks through interchangeable drivers:

The first three come preconfigured and you see them with:

A quick look at host and none, which are rarely used but worth recognizing:

With --network host, the container has the same IP as your machine: no -p is of any use because the ports are the host's directly, and there is no network isolation at all. With --network none, only lo exists: it cannot even ping anything.

Here is the heart of the lesson. There are two kinds of bridge network and they behave very differently:

Only the first row matters today, but it is decisive: on a network of your own, Docker brings up an internal DNS server at 127.0.0.11 that resolves the names of the containers connected to that network. On the default bridge, that DNS exists but it only forwards queries to the host's servers: it knows no container names. That is, literally, the whole mystery you have been dragging along since lesson 02-06.

Before fixing it, put the starting point on record:

With options, when you need control:

--internal deserves attention: an internal network lets containers talk to each other but cuts their access to the outside world. It is an excellent defense for a database that has no business going out to the Internet, and it is picked up again in lesson 05-03.

And the most useful query of all: who is connected.

For now it prints nothing: the network is empty.

A network with containers connected cannot be deleted (network ... has active endpoints). And the three predefined networks —bridge, host, none— can never be removed.

Now that you understand the model, the table from lesson 03-01 makes full sense:

And this is the distinction you must be absolutely clear about:

From that come two classic mistakes you can now avoid:

• Publishing ports "so the containers can see each other". It is unnecessary and on top of that it exposes internal services. aurora-db needs no -p for the API to use it; you only need it if you want to connect with a client from the host.
• Using the host port in another container's connection string. If you publish -p 5433:5432, another container must still connect to aurora-db:5432, the internal port. 5433 only exists for the host.

Let's get to work. First, the network:

Now recreate the three services inside it. Since the network is a namespace setting, it is frozen when the container is created (lesson 03-01), so we have to delete and create again:

Notice an important change in aurora-cache: it no longer carries -p. Nobody on the host needs to talk to Redis; only the API does, and for that being on the same network is enough. It is the principle of exposing the bare minimum.

Before starting the API, load the catalog again, because the database container is new:

Note this nuisance, because it is the second time you have suffered it: every time you recreate aurora-db you lose the data and have to load it by hand again. That is the gap lesson 03-06 fills.

And now the API:

There it is. The same command that ten minutes ago returned code 2 and not a single line now resolves all three names. You have not changed a line of server.js, or the Dockerfile, or the environment file: you have only put the containers on a network of their own.

Check the real connectivity too, port by port:

All three, by name. And note the detail: aurora-cache answers on 6379 even though you published no port. Publishing is for the host; inside the network, all of a container's ports are available to its neighbors.

And the state of the fleet:

(healthy). That parenthesis has been saying unhealthy for four lessons. The HEALTHCHECK you wrote in lesson 02-04 runs its check against /health, /health queries PostgreSQL and Redis, both respond, and for the first time it returns 200. And look at aurora-cache's line: a bare 6379/tcp, with no arrow. Exposed but not published.

db: ok. cache: ok. And now, the command you have been waiting for all course:

All eight books. El jardín de senderos que se bifurcan, Rayuela, Cien años de soledad, La sombra del viento, Nada, La casa de los espíritus, Los detectives salvajes and El tiempo entre costuras, sorted by title, served by an API in a container, read from a PostgreSQL database in another container, across a virtual network you created yourself. Stop for a second on this: the Aurora Libros platform is alive. It is the first time since lesson 01-07, where you ran it by hand in fifteen steps and it failed, that the complete system works end to end.

And there is a second, subtler check that proves the cache is doing its job too:

The first call went to PostgreSQL and stored the result in Redis with a TTL of 60 seconds; the second one served it from the cache. The three containers are cooperating: the API talks to the database by its name and to the cache by its own. Check it from the other end too:

That last row is the lesson to take away: the problem was never in the application or in the image. It was in how the containers connected to each other.

The fourth service is missing. Your web/index.html from lesson 01-07 calls /api/books, a relative path, not http://localhost:3000/books. That design was deliberate: the browser should talk to a single origin, and the one distributing the traffic inside is Nginx.

Create ~/aurora-libros/web/nginx.conf:

Line by line, what matters:

Start the container:

Two details of the command:

• The two -v flags mount host files read-only (:ro). It is the minimal syntax from lesson 03-01; lesson 03-06 explains what exactly these mounts are and why :ro matters on configuration files.
• --stop-signal SIGQUIT applies what you learned in lesson 02-04: Nginx performs a graceful shutdown on SIGQUIT and an abrupt one on SIGTERM. With this option, docker stop aurora-web does not cut off half-served requests.

Check the complete chain:

Open http://localhost:8080 in your browser. The Aurora Libros page loads, calls /api/books, Nginx forwards it to aurora-api, the API queries PostgreSQL or Redis, and the table fills up with the eight titles and their prices in euros. The complete architecture, working:

Not a single hand-written IP anywhere: aurora-web looks for aurora-api, and aurora-api looks for aurora-db and aurora-cache, all by name.

With user-defined networks, and only with them, you can change the topology without recreating anything:

aurora-db now has two interfaces and two IPs, one on each network. It is the usual pattern for giving an administration tool access without opening up the application's network:

Adminer sees the database, but it does not see aurora-api or aurora-cache, because it is not on aurora-net. Isolation by design.

And a note about network aliases, which will be important in module 4:

A container can answer to several names on the same network. That is what allows you, for example, to swap the implementation without touching the configuration of whoever consumes it.

Here is how Aurora Libros's exposed surface looks:

In a real deployment, even the API's -p 3000:3000 would be unnecessary: if the browser only talks to Nginx, the API does not need to be published. You can try it by recreating it without -p and you will see that http://localhost:8080/api/books still works perfectly, because the proxy reaches it over the internal network.

What this lesson does not cover, and where you will see it: how the bridge works internally (veth pairs, iptables, nat), overlay networks across several hosts, macvlan and network policies are studied in lesson 05-01 and in 06-03.

• Using localhost to refer to another container. Inside a container, localhost is itself. Use the other container's name.
• Leaving containers on the default bridge and expecting them to resolve by name. It will never happen. Create a network with docker network create.
• Writing IPs by hand. It works until the next restart. Docker assigns IPs in start-up order.
• Using the published host port in a container-to-container connection. With -p 5433:5432, another container must still use 5432.
• Publishing ports "so they can see each other". It is unnecessary, and it exposes internal services to the whole network.
• Trying to change network with docker start. The network is frozen at creation. You change it with network connect/disconnect, or by recreating.
• 502 in Nginx after recreating the API. Nginx cached the old IP. It is solved with resolver 127.0.0.11 valid=10s and a proxy_pass over a variable, as in this lesson's configuration.
• Forgetting the trailing / in proxy_pass. Without it, /api/books is forwarded as /api/books and the API answers 404. With it, it arrives as /books.
• Tip: docker network inspect is the fastest way to answer "who is on this network and with which IP?".
• Tip: to diagnose, launch netshoot connected to the network (--network aurora-net) and try nc, dig and curl from inside it.

Create two networks, net-a and net-b. Bring up a server-a container with nginx:alpine on net-a, and two nicolaka/netshoot clients: client-a on net-a and client-b on net-b. Prove with commands that:

1. client-a resolves server-a by name and gets an HTTP 200.
2. client-b does not resolve it and cannot reach it, neither by name nor by IP.
3. Then, without recreating anything, make client-b able to reach it, and check how many IPs it has after that.

Bring up a minimal stack on a shop-net network: a mini-db with redis:7-alpine with no -p at all, and a mini-api with nicolaka/netshoot running sleep 3600, publishing -p 9999:80. Answer with commands and explanations:

1. Can mini-api talk to mini-db? Prove it.
2. Can you, from the host, talk to mini-db with redis-cli or nc? Why?
3. What does curl localhost:9999 answer and why, if mini-api has no web server at all?
4. Recreate mini-db with -p 127.0.0.1:6380:6379 and repeat point 2. Has anything changed for mini-api?

With the Aurora Libros platform working, cause and diagnose two real proxy breakdowns:

1. Change the destination in nginx.conf to http://aurora-api-nonexistent:3000, reload Nginx with docker kill -s SIGHUP aurora-web and observe what curl localhost:8080/api/books returns. Diagnose it with docker logs aurora-web.
2. Restore the correct destination but remove the trailing slash from proxy_pass. Reload and observe the new error. Explain exactly which path is reaching aurora-api (check it with docker logs aurora-api).
3. Leave everything correct and prove, by recreating aurora-api without -p, that the site still works at localhost:8080.

Solution to exercise 1

1. From client-a:

2. From client-b:

There are two different failures here and both matter: the name does not resolve (they do not share a network, so net-b's DNS knows nothing about server-a) and the IP does not work either, because they are two separate bridges and traffic between them is not allowed. Compare it with the diagnosis in lesson 03-04: there the name failed but the IP worked, which proved they did share a network. The combination of the two tests is what distinguishes "same network with no DNS" from "different networks".

3. Connecting on the fly:

Two IPs, one per network, without having stopped or recreated the container. That is only possible with user-defined networks.

Solution to exercise 2

1.

Yes, perfectly, and mini-db publishes no port. Inside a shared network, all of a container's ports are available to its neighbors: -p has nothing to do with it.

2.

No. Since mini-db published no port, there is no rule forwarding traffic from the host towards it. The host and Docker's network are two different realms: the host only reaches what has been explicitly published.

3.

The publishing rule exists —docker ps shows 0.0.0.0:9999->80/tcp— but inside the container nothing is listening on 80: mini-api only runs sleep. It is the proof that -p checks nothing: it creates the forwarding even if the destination is empty. It is the same mistake made when reversing the order in -p 80:8080.

4.

Now you can connect from the host on port 6380, and for mini-api absolutely nothing has changed: it still uses mini-db:6379, the internal port. The two paths are independent.

Solution to exercise 3

1. Non-existent destination:

502 Bad Gateway is the "the proxy could not talk to the destination" error, and the log gives the exact reason: could not be resolved. It is the same NXDOMAIN from lesson 03-04, seen from Nginx. And it is worth noting that the static site is still served without a problem at http://localhost:8080/: only the /api/ route fails.

2. Without the trailing slash:

Now it does reach the API, but with the wrong path. With the trailing slash, proxy_pass http://aurora-api:3000/ replaces the /api/ prefix with /, so /api/books arrives as /books. Without it, Nginx concatenates the full path and the API receives /api/books, a route server.js does not define, hence Express's 404. A single character, and half of the world's misconfigured proxies are explained by it.

3. Restoring and removing the API's publishing:

Exactly what we were after: from the host, port 3000 no longer exists; from the site, the eight books still arrive. The API has stopped being exposed and the service has not suffered, because Nginx reaches it over the internal network. It is precisely the architecture you would want in production: a single front door.

Since in the coming lessons it is handy to be able to call the API directly for testing, publish it again:

The mystery is solved and the platform is alive. You know that each container has its own network stack and its own localhost, and that this is why localhost:5432 inside the API was asking for a database that was never there. You know the built-in drivers —bridge for almost everything, host when you want neither isolation nor NAT, none for total isolation— and you know that overlay, macvlan and ipvlan exist for multi-host scenarios and integration with the physical network that you will see in lessons 05-01 and 06-03.

And you have nailed the difference that explained everything: the default bridge has no internal DNS; a user-defined network does. One docker network create aurora-net and one --network aurora-net on each container, and getent hosts aurora-db went from returning code 2 to returning 172.18.0.2 aurora-db. Without touching a line of server.js, or the Dockerfile, or the environment file. You also know how to connect and disconnect networks on the fly to give an administration tool one-off access, and how to give a container network aliases.

You distinguish publishing a port from connecting two containers: -p is for the host and the outside world to get in; inside the network, every port is available by name without publishing anything. That is why aurora-cache no longer carries -p, aurora-db is bound to 127.0.0.1, and you have proved that even the API can live without publishing if Nginx is the only front door.

The result, in one line: curl http://localhost:3000/books returns the eight Aurora Libros books, served by Node from PostgreSQL, cached in Redis with its 60-second TTL, and http://localhost:8080 shows the complete bookshop in the browser through a reverse proxy that forwards /api/ without exposing the API. The healthcheck reads healthy for the first time in the whole course. Four containers, one network, zero hand-written IPs.

One problem remains, and you have already suffered it twice in this very lesson: every time you recreate aurora-db, the eight books disappear and you have to load init.sql again with docker cp. The data lives in an anonymous volume nobody controls, or straight in the writable layer that dies with the container. In the next lesson, Data Persistence with Volumes, you will attack that problem at its root: you will see the three types of mount —managed volumes, bind mounts and tmpfs—, the difference between -v and --mount, where volumes really live and why you should not touch them by hand. You will give PostgreSQL the aurora-data volume, mount init.sql so it runs by itself, and repeat the definitive test: insert a new book, destroy the database container, recreate it, and check that the book is still there.