You have the four services declared and you have mastered the CLI. What is missing is what truly turns four containers into an application: how they find each other, what is allowed to talk to what, and in what order they have to be ready.

In this lesson you assemble the definitive Aurora Libros stack: internal DNS, two segmented networks so the web front end cannot touch the database, coordinated startup with real health probes, a migration service that runs once and finishes, and the retry pattern you need even when everything above is right. By the end, the fifteen onboarding steps from lesson 01-07 will be down to two.

1. The final architecture
2. How services find each other: Compose's DNS
3. Who talks to whom and over which port
4. Segmentation into two networks
5. Demonstration: the web front end cannot reach the database
6. Startup order: why a bare depends_on is not enough
7. Real health probes and condition: service_healthy
8. A service that runs once: service_completed_successfully
9. Why the application must retry anyway
10. The complete, commented compose.yaml
11. End-to-end startup
12. The onboarding tally

aurora-api is the only service that sits on both networks: it is the border. Everything coming in from outside goes through aurora-web, and everything that touches the data lives on a network with no way out.

In lesson 03-05 you saw that a user-defined bridge network comes with an internal DNS server at 127.0.0.11. Compose leans on exactly that, with one precision worth committing to memory:

A service's host name is the service name, not the container's.

The container is called aurora-libros-aurora-db-1, but from the API you connect to aurora-db. Compose registers these names in each network's DNS:

Aliases are extremely useful when migrating: if legacy code looks for postgres, you add aliases: [postgres] and it works without touching a single line of the application.

One important consequence: resolution is per network. A service only resolves the names of the services it shares a network with. That is the basis of the segmentation in section 4.

Here is the most repeated conceptual mistake with Compose: using the published port instead of the internal one. Publishing (ports) is a door from the host inwards; between containers it plays no part whatsoever.

Only the first row uses a published port, because it is the only one that comes in from the host. The rest travels over Docker's internal network.

This is reflected in the web/nginx.conf you already wrote in module 3, where proxy_pass http://aurora-api:3000/; uses the service name and the internal port. And in the API's variables: DB_HOST=aurora-db, REDIS_HOST=aurora-cache. No localhost, no IP addresses, no published ports.

With a single network, all four services can see each other. It works, but it means that if somebody compromises the nginx container —the most exposed one, the only one receiving traffic from outside— they get direct access to PostgreSQL's port 5432. Good practice is to segment by zone:

internal: true does two things: containers on that network have no route to the outside (they cannot even ping the Internet) and nobody outside the host can reach them. If a compromised PostgreSQL dependency tried to phone home, it would have no way to.

A side effect worth knowing: a container connected only to internal networks cannot publish ports on the host. That is why aurora-db stops publishing 127.0.0.1:5432; to get at the database you will use docker compose exec, and the development environment (lesson 04-07) will expose it again by adding the service to a non-internal network.

Segmentation is not theory: you can check it.

The first one resolves; the second returns nothing and exits with code 2. aurora-web and aurora-db share no network, so as far as nginx is concerned the database simply does not exist in DNS. With the network toolbox from lesson 03-04, the difference between the two networks is stark:

From frontend the name does not even resolve; from backend it connects; and the database itself has no route to the Internet. That is the difference between "it works" and "it works and it also contains the damage". Full hardening arrives in lesson 05-03.

Try what happens with no condition at all, with depends_on: [aurora-db] on the API:

Compose kept its promise: it started aurora-db first. The problem is what "first" means. There are three distinct states and only the third one is any use:

PostgreSQL takes between 3 and 10 seconds from the moment the process starts to the moment it accepts connections, and on the first startup, with init.sql still to run, considerably longer. The distinction between "started" and "ready" is what breaks half the compose.yaml files out there.

The solution has two halves. First: probes that tell the truth about each service.

Second half: declaring the dependency on health, not on startup.

Now Compose does not launch the API until both probes pass. If one never reaches healthy, up --wait fails with a clear message instead of leaving you a service restarting in a loop.

Aurora Libros needs to apply the schema and the migrations before the API serves requests. That is not a permanent service: it is a task that runs, finishes and disappears.

And the API waits for it to finish successfully:

Two details people overlook: restart: "no" is essential —with an unless-stopped inherited from an anchor, the container would restart in an endless loop every time it finished— and so are the quotes, because a bare no is the boolean false in YAML. On top of that, the condition demands exit code 0: if the migration fails, the API is not even created, and that is precisely the right behavior.

With everything above, cold startup is solved. But not the other cases: if aurora-db restarts at three in the morning because of a disk failure, the API is already running and depends_on is not evaluated again; in an orchestrator, containers are rescheduled in any order; and a two-second network blip is not something any YAML file can fix.

depends_on solves startup; reconnecting is the application's responsibility. Add a retry with exponential backoff to api/server.js:

Three design decisions: exponential backoff avoids hammering a database that is still starting up, the random jitter stops ten replicas from retrying in unison, and the SELECT 1 test is what separates "I have a connection object" from "the database is answering me". The cache deserves different treatment: if Redis is down, /books must keep serving from PostgreSQL with source: db. A cache is an accelerator, never a hard dependency.

A hundred and thirty commented lines that replace fifty lines of bash and, above all, express things the script could not say: who depends on whom, what being ready means, and what is allowed to talk to what.

Read the sequence: the two networks and the volume first, then database and cache up to Healthy, then the migrations up to Exited with code 0, and only then the API and the web front end. You no longer write the order: Compose deduces it from the dependency graph.

The acid test: cache-aside in action and, after that, the resilience we demanded in section 9.

First request from PostgreSQL, second from Redis: the nine titles crossing web → api → db → cache exactly as designed, and http://localhost:8080 in the browser shows the full catalog. And with the cache stopped, the API keeps serving from the database: graceful degradation, you lose speed, not service.

That is all. Someone joining the team today has the complete platform —four services, two networks, one volume, migrations applied and health probes verified— in under a minute, and with exactly the same configuration as the rest of the team, because it is in Git.

Using the published port between containers. DB_HOST=localhost:5432 from the API finds nothing: inside the container, localhost is the container itself. Service name and internal port, always.

Trusting depends_on without condition. It only guarantees startup order. Without health probes, you will still have races.

Probing the port instead of the service. nc -z aurora-db 5432 comes back green while PostgreSQL is still refusing connections. Use pg_isready.

Forgetting restart: "no" on a one-shot service. With an inherited policy, the migration restarts in a loop and service_completed_successfully is never met.

Assuming depends_on reconnects. It is not re-evaluated after startup. Reconnecting with retries is the application's job.

Treating the cache as a hard dependency. If your API dies because Redis is not answering, you have turned an optional accelerator into a single point of failure.

Tip: when two services cannot see each other, the first check is always docker compose exec <source> getent hosts <destination>. If it does not resolve, it is not an application problem: they simply do not share a network.

Exercise 1. Add the network alias postgres to aurora-db and prove that the API can connect equally well through aurora-db or through postgres, but that aurora-web resolves neither of them.

Exercise 2. Break the startup on purpose: make aurora-migrations exit with code 1 (for example, command: ["sh", "-c", "echo 'migration failed'; exit 1"]) and observe what docker compose up -d --wait does with the API and the web front end. Explain the result and why it is the desirable behavior.

Exercise 3. Prove that backend's isolation is real in both directions: (a) aurora-db cannot reach the Internet, (b) from another machine on your local network port 5432 cannot be reached, and (c) aurora-api can reach the Internet. Explain why (c) works despite it being on the internal network.

Solution 1.

The same address for both names: the alias is an extra DNS entry on that network, not another container. For aurora-web, exit code 2 (it does not resolve), because aliases live inside the network in which they are declared and nginx is not on backend. This is the mechanism for migrating a service without touching its clients' code: first you add the new alias, then you change the service name.

Solution 2.

Neither aurora-api nor aurora-web ever gets created. Compose cuts the chain: if a dependency with service_completed_successfully exits with a non-zero code, everything depending on it is cancelled, and that failure cascades on to the web front end, which depends on the API.

That is exactly what you want. The alternative —starting the API against a half-migrated schema— would produce intermittent errors, corrupted data and an hour of debugging. On top of that, --wait returns exit code 1, so a CI pipeline goes red automatically instead of carrying on over a broken foundation. Compare with the module 3 bash script: there, if step 4 failed, steps 5, 6 and 7 ran anyway.

Solution 3.

(a) and (b) confirm the double isolation: internal: true removes that network's default route, and since aurora-db has no ports, there is no rule on the host redirecting traffic towards it —not even from the host itself, let alone from another machine on the local network.

(c) works because aurora-api is on both networks. A container connected to several networks has an interface on each one, and its default route comes from frontend, which is not internal. Hence the API being the "border": it is the only point through which the data zone communicates with the world, and therefore the only one you have to watch closely.

Aurora Libros is properly assembled now. You know that services find each other by the service name —not the container's— thanks to each network's internal DNS, that aliases add extra names within the network where they are declared, and that between containers you always use the internal port: publishing ports only opens a door from the host, and in this architecture there is exactly one, the web front end's 8080.

You have segmented the platform into two zones: a frontend one with the web front end and the API, and a backend one marked as internal with the data and the migrations, and you have demonstrated it in both directions —nginx cannot even resolve the database's name, and PostgreSQL has no route to the Internet— with aurora-api as the sole border by virtue of being on both networks. And you have startup solved with the distinction that separates a file that works on your laptop from one that always works: started is not the same as ready. pg_isready and redis-cli ping as honest probes, condition: service_healthy to wait until they are, service_completed_successfully with restart: "no" for the migration that runs once, and retry with exponential backoff and jitter in the application, because depends_on covers startup and nothing else. The cache, treated as what it is: an accelerator whose failure degrades the service but does not take it down.

The tally speaks for itself: from fifteen manual steps to a fifty-line script, and from there to git clone and docker compose up -d --wait. But the file still has passwords written in the clear, the image version pinned by hand and the ports hardcoded: exactly what stops you from using it in more than one environment. In the next lesson, Environment Variables in Docker Compose, you will separate the two systems everybody confuses —the ${VAR} substitution Compose performs on the YAML itself, and the variables the process inside the container sees— with their complete precedence table, the project's .env file and its versioned .env.example, and the secrets: block so that credentials stop being visible in a docker inspect.