Aurora Libros works: four containers on a network of their own, the catalog safe in a named volume, the site served through a reverse proxy. But two risks remain, both of which appeared in earlier lessons and both of which, on a real server, end in a three-in-the-morning phone call.

You saw the first one in docker stats: the LIMIT column showed 7.628 GiB on every container, that is, all the machine's RAM. A runaway query in PostgreSQL or a memory leak in Node can leave the entire host out of memory and drag the other three services down with it. The second one is simpler: if a container dies at three in the morning, there it stays until somebody brings it back up.

This lesson closes both fronts. You are going to set memory, CPU, disk and process-count limits, you are going to trigger an OOM on purpose to see it with your own eyes, and you are going to configure restart policies with their subtle differences. And by the end, you will have in front of you the complete list of commands needed to bring the platform up from scratch... and you will understand perfectly why module 4 exists.

1. Why a container with no limits is a problem
2. Memory limits
3. The OOM killer, triggered and diagnosed
4. CPU limits
5. Disk I/O limits
6. --pids-limit: defense against a fork bomb
7. Verifying and changing things on the fly
8. Restart policies
9. always versus unless-stopped
10. Why a restart policy does not replace a healthcheck
11. Final hands-on: the Aurora Libros limits table
12. The complete script, and why it cannot go on like this

All four have the same limit: all of the host's memory. By default, a container can consume as much RAM and as much CPU as there is available. Remember from lesson 01-01 that a container is not a virtual machine with preassigned resources, but a host process isolated with namespaces; what distributes resources is the cgroups, and by default they are wide open.

The consequences, all of them real:

The idea that holds this whole section together: limits are not an optimization, they are a containment mechanism. They are there so that one service's failure does not become the whole machine's failure.

The units are b, k, m and g: -m 512m, -m 1g. The minimum accepted is 6 MB.

This is the part that confuses everybody, because --memory-swap is not the amount of swap: it is the total of memory plus swap.

The most important row is the third: --memory and --memory-swap with the same value disables swap. And that is usually the right configuration on servers, because a process that starts swapping to disk is not working, it is dying: response times shoot up until the service is useless, but since it is technically still alive, healthchecks may never notice. A clean, fast failure is preferable to slow, silent degradation.

Now the LIMIT column says 256 MiB instead of the host's 7.628 GiB.

The difference between the two:

The usual pattern is to use both: reserve the expected normal consumption and set the limit at the point where something is clearly wrong.

With this option, when memory runs out the kernel does not kill the process: it freezes it indefinitely. It sounds better and it is almost always worse: you end up with an Up container that responds to nothing, with no new logs and no exit code to investigate. A dead process gets restarted; a frozen one has to be diagnosed by hand. Use it only if you know exactly why, and never without a memory limit (without -m, you would freeze the entire machine).

When a container exceeds its memory limit, the Linux kernel's OOM killer (Out Of Memory killer) steps in. It is not Docker: it is the kernel, and it does not negotiate.

Let's trigger it. This container has 64 MB and is going to try to write 200 MB into shared memory, which counts against the same cgroup:

Code 137. From lesson 03-02's table: 137 = 128 + 9 = SIGKILL. But that same 137 is also produced by a docker kill or by a docker stop that runs out of time, so one more piece of evidence is needed:

OOMKilled: true is the unambiguous confirmation. And look at the logs: you can see the "starting to fill memory" but never the "I have finished". The process was eliminated mid-task, with no chance to write anything else, no catchable exception and no graceful shutdown. SIGKILL cannot be intercepted.

The event is also recorded in the daemon:

And on the host, the kernel leaves its own record:

How to diagnose a suspicious 137, in order:

Three options that do different things and get confused constantly:

An infinite loop that would devour an entire core stays at 50% of one, which is exactly what --cpus 0.5 asked for. Bear in mind that in docker stats 100% equals one core: a container with --cpus 2 can reach 200%.

The ratio is roughly 4:1, exactly the relationship between 1024 and 256. But the key is elsewhere: if weight-low were alone on the machine, it would use all the available CPU. Shares only come into play when there is competition; they do not waste idle capacity.

The container will only run on cores 0 and 1, whatever the load on the rest. It is rarely used, but it is valuable for latency-sensitive workloads (it stops the scheduler moving the process between cores and losing the caches) and for reserving cores for critical system processes.

Less common, but essential when a container saturates the disk and drags the others down:

Exactly 1 MB/s, ten seconds for ten megabytes. Two warnings: you have to give the host's real device (/dev/sda, /dev/nvme0n1; find it with lsblk), and these options only work with the right storage driver and file system —in many setups with overlay2 over ext4 they require oflag=direct to be noticeable, as in the example.

It limits the number of processes and threads a container can create. It is the cheapest and one of the most effective protections:

From process number 20 onwards, the kernel denies the fork(). Without this limit, a fork bomb —a bug or an attack that creates processes non-stop— exhausts the host's process table, and from that point on you cannot even launch a ps to diagnose it: you have to reboot the machine.

Reasonable values: 100 for a simple web service, 200–500 for a database, and always measuring the normal consumption with docker stats beforehand, with a generous margin.

A 0 means "no limit", and NanoCPUs expresses --cpus in billionths: --cpus 1.5 is stored as 1500000000.

The great advantage of these options, compared with ports, networks and mounts, is that they can be changed without recreating the container, because they live in the cgroups and not in the namespaces:

Without stopping PostgreSQL, without recreating the container and without losing a single connection. The LIMIT column now says 512 MiB. It is the exception to the "everything is frozen at creation" rule, and that is why docker update exists.

Two limitations of docker update: it cannot lower the memory below what is already in use (it would fail), and some options such as --memory-swap require you to give --memory in the same call.

A container that dies does not come back on its own. The --restart option changes that:

Four "attempt" lines in the logs: the original start plus three restarts, and then Docker gives up. RestartCount is the counter that confirms it and it is one of the first fields to look at when a service "comes and goes".

Docker does not restart in a tight loop: it waits longer and longer between attempts.

The counter is reset if the container manages to stay up for at least 10 seconds. That detail explains a baffling behavior: a service that starts, works for 30 seconds and dies can, with --restart always, stay restarting forever every few seconds without the backoff ever growing. You detect it like this:

A RestartCount of 847 is a service that has been failing for hours with nobody noticing.

The two look identical and differ in a single scenario, which happens to be the most important one: when the Docker daemon or the machine restarts.

Why it matters: imagine you stop aurora-api to investigate a problem and go for lunch. With always, a daemon restart —an automatic update, a server reboot— brings it back up in the broken state you were investigating. With unless-stopped, your decision is respected.

General recommendation: unless-stopped for long-running services and on-failure:N for processes that are meant to finish. always only if you genuinely want nothing to be able to leave the container stopped.

And two operational nuances:

• The policy can be changed on the fly: docker update --restart unless-stopped aurora-db.
• With --rm, --restart is incompatible: Docker rejects it, because it cannot both delete and restart the container.

This is the nuance that separates a configuration that looks robust from one that is.

Nginx is stopped inside the container and Docker says Up, perfectly happy, because PID 1 is still alive (the Nginx master has not fully terminated yet). Generalizing the problem:

And now the detail that surprises people: Docker Engine does not restart a container for being unhealthy. The restart policy reacts to the process dying, not to the healthcheck's verdict. You can have a container reading Up 3 days (unhealthy) with --restart always for three days without anyone doing anything.

So who acts on health?

The conclusion, worth being clear about as you leave this module: the restart policy and the healthcheck solve different problems and complement each other. The first brings back a dead process; the second detects a process that is alive but useless. And for that diagnosis to translate into action you need an orchestrator, which is where module 6 leads.

It is time to decide concrete numbers, and to decide them with judgment. Start from what they really consume:

The table, with its justification:

Two decisions deserve a separate explanation:

Why aurora-cache carries --maxmemory in addition to the container's limit. If you only set -m 256m, Redis would know nothing about that limit: it would keep accepting keys until the OOM killer struck it down, losing the whole cache. With --maxmemory 200mb --maxmemory-policy allkeys-lru, Redis handles the problem itself: on reaching 200 MB it starts evicting the least recently used keys and carries on working. The container's limit becomes the safety net, not the usual mechanism. When a service has its own memory control, configure it below the container's limit. The same applies to --max-old-space-size in Node and to shared_buffers in PostgreSQL.

Why aurora-api carries on-failure:3 and not unless-stopped. It is a stateless, replaceable service, but if it fails three times in a row it is almost never something transient: it is a badly set environment variable, a pending migration or a dependency failure. Restarting infinitely turns a visible error into a silent loop that fills the logs and hides the diagnosis.

Apply the table. aurora-db is already updated, so the policy is all that is needed:

The other three have to be recreated, because aurora-cache also changes its command and aurora-api and aurora-web had no limits:

Verify:

Four real limits instead of four times 7.628 GiB. And the percentages are healthy: between 3% and 21%, with plenty of headroom for spikes.

All four with their limits, their policies, and the nine books were still there after destroying and recreating three containers. The aurora-data volume did its job.

A final resilience test: kill the API brutally and see what happens.

It came back on its own in under three seconds and the site started working again without anyone touching a thing. That is exactly the difference between a pile of containers and a platform.

Let's recap. This is everything you have to write, in the right order, to bring Aurora Libros up on a clean machine:

Look at that script with a critical eye. It works, it is correct and it contains everything you have learned in seven lessons. And it is a problem:

And now picture the real scene: someone new joins the Aurora Libros team. You send them this file over chat, and you hope their $HOME has the same structure, that image 1.2.0 is the right one, that nobody changed a value without saying so. It is the modern version of those fifteen manual onboarding steps from lesson 01-07: you have reduced the problem enormously, but you have not eliminated it. You have turned it into a bash script nobody wants to maintain.

There is an answer to exactly this, and it is the module that comes next.

• Setting no limits at all "because the machine has plenty of RAM". It does, until one container eats it all and the kernel starts killing processes at random, system ones included.
• Confusing --memory-swap with "the amount of swap". It is the total of memory plus swap. -m 512m --memory-swap 512m is what disables swap.
• Reading every 137 as a docker kill. Check .State.OOMKilled before drawing conclusions.
• Using --cpu-shares expecting a hard limit. It only acts under contention. For a real ceiling, --cpus.
• Setting a memory limit without adjusting the service's own. Redis with no --maxmemory, Node with no --max-old-space-size or the JVM with no -Xmx will crash into the container's limit and die outright instead of managing it.
• Trusting --restart always as if it were high availability. It does not detect a process that is alive but hung, and it does not fix a configuration error: it just repeats it faster.
• Expecting Docker to restart an unhealthy container. Docker Engine only marks it. Acting is an orchestrator's job.
• Using always instead of unless-stopped. With always, a daemon restart brings back up containers you had deliberately stopped.
• Tip: measure before you limit. Leave the service running under real load, look at docker stats, and set the limit with a margin of two or three times the observed peak.
• Tip: docker update is your friend for adjusting limits and policies in production without recreating anything or dropping connections.

Create a glutton container with 100 MB of memory and no swap that tries to occupy 300 MB in /dev/shm. Then:

1. Check the state, the exit code and the value of OOMKilled.
2. Locate the corresponding event with docker events.
3. Repeat the experiment with a 512 MB limit and check that it now finishes properly.
4. Repeat the first case but with --memory-swap 1g instead of no swap. Explain what changes and why that is rarely a good solution.

Launch two containers that consume CPU with an infinite loop and measure how it is shared with docker stats in three scenarios:

1. container-a with --cpus 0.5 and container-b with no limit at all.
2. Both with --cpu-shares, one with 1024 and the other with 512.
3. Only the --cpu-shares 512 one, running alone.

Explain the three results and answer: which of the two options would you use to guarantee a client that their container will never exceed half a core? And to share a machine between a critical service and a testing one while taking advantage of all the available CPU?

Design an experiment that demonstrates the difference between always and unless-stopped without rebooting your machine (hint: sudo systemctl restart docker restarts the daemon; on Docker Desktop, use "Restart" from the menu). Create two identical containers, one with each policy, stop both manually and then restart the daemon. Note which containers are running when you come back. Finally:

1. Create a third container with --restart on-failure:2 that always fails and check RestartCount when it gives up.
2. With the Aurora Libros platform, make aurora-api go unhealthy (stop aurora-db) and prove with commands that the restart policy does nothing about it. Then fix the situation.

Solution to exercise 1

The logs are empty: it did not even get to print "FINISHED". SIGKILL gives no room for anything.

The complete sequence in four lines: creation, start, oom and death with 137. That oom event is the proof from the daemon's side.

3. With enough headroom:

4. With swap:

Now it survives, because it has 100 MB of RAM plus 924 MB of swap. But look at the time: 11.84 seconds versus less than one with real memory. That is why swap is rarely the answer: the container does not die, but it runs between ten and a hundred times slower. In a service with users waiting, that is indistinguishable from an outage, with the added problem that no alarm goes off: there is no OOM, no restart, no code 137. Just an unbearably slow service nobody can explain. A fast, noisy failure is preferable.

Solution to exercise 2

1. cpu-a respects its half core even though the machine has capacity to spare; cpu-b, with no limit, takes up a whole core. The hard limit does not give way even when there is spare CPU.

2. The ratio is 2:1, exactly 1024 against 512. 3. And as soon as cpu-high disappears, cpu-low jumps to 398%: almost four cores. Shares never waste idle capacity.

The two answers:

• To guarantee a client that it will never exceed half a core: --cpus 0.5. It is an absolute ceiling, verifiable and independent of what everyone else does. It is what gets billed and what you can promise in a contract.
• To share a machine between a critical service and a testing one: --cpu-shares, for example 1024 and 256. When both compete, the critical one gets four times as much; when the critical one is idle, the testing one uses the whole machine instead of leaving it standing still. It is a distribution of priorities, not a ceiling.

Solution to exercise 3

Both stopped by your decision. Now restart the daemon:

The difference, in two lines. always ignored your manual stop and started the container again; unless-stopped respected your decision and left it stopped. It is exactly the scenario from section 9: if you had stopped aurora-api to investigate an incident, with always you would have found it running again when you got back.

1. The retry counter:

RestartCount: 2: the original start plus two retries, and Docker gives up while preserving the real failure code (7), not a generic one. That code is what lets you diagnose.

2. The policy does not react to health:

The demonstration is emphatic: the container has been unhealthy for twelve minutes, the API returns 500 to users, and RestartCount is still 1 —the restart from the docker kill in the hands-on section, not a new one. The restart policy has not lifted a finger, because the node process never died. It only lost its database.

And as soon as aurora-db comes back, the healthcheck recovers on its own: /health returns 200 again, the state turns healthy and the nine books come back. Without restarting the API, because it was never needed. Note two things: the API survived its database going down thanks to the change you made in lesson 03-02, and the correct diagnosis —a sustained unhealthy with a frozen RestartCount— is the unmistakable signature of "the process is fine, its dependencies are not".

The module is closed and the platform is, at last, something you can defend. You know that by default a container can consume all the host's RAM and all its CPU, and you know how to fence it in: -m as the hard limit, --memory-reservation as the soft limit that decides who gives up memory under pressure, and --memory-swap with the trap that confuses everybody —it is the total, and with the same value as --memory swap is disabled, which is almost always the right thing. You have triggered an OOM on purpose and diagnosed it with the signature that leaves no doubt: OOMKilled: true, code 137 and an oom event in the daemon, with the logs cut off mid-sentence because SIGKILL cannot be caught.

You distinguish the three ways of sharing CPU: --cpus as an absolute, predictable ceiling, --cpu-shares as a relative weight that only acts under contention and never wastes idle capacity, and --cpuset-cpus for pinning specific cores. You know how to throttle disk I/O with --device-write-bps and, above all, you know that --pids-limit is the cheapest defense there is against a fork bomb that, without it, takes down the entire host's process table. And you know how to verify it all with docker stats and inspect, and change it on the fly with docker update without recreating a single container, because resources live in the cgroups and not in the namespaces.

You know the four restart policies and the difference that only shows up when the daemon restarts: always ignores your manual stop and unless-stopped respects it. You know how to read RestartCount, recognize the exponential backoff and spot a container that has racked up 847 restarts with nobody noticing. And you take away the distinction that prevents the most confusion: a restart policy brings back a dead process, a healthcheck detects a process that is alive but useless, and Docker Engine restarts nothing for being unhealthy; for that you need an orchestrator. Aurora Libros has it all applied with judgment: aurora-db with 512 MB and unless-stopped, aurora-cache with 256 MB and a Redis --maxmemory 200mb aligned below so it evicts keys instead of dying, aurora-api with 256 MB and on-failure:3 so a configuration error does not hide in an infinite loop, and aurora-web with 128 MB to spare. One docker kill aurora-api and the service came back on its own in under three seconds.

And yet, look again at that script in section 12. Fifty lines of bash for four containers: one network, one volume, four docker run commands of fourteen lines each, a wait loop written by hand so the API does not start before PostgreSQL, --network aurora-net repeated four times, no command to stop the whole platform and no way of knowing whether what is running matches what the file says. Adding an environment variable to the API means deleting the container and pasting its exact fourteen lines again without getting the volume wrong. It is correct, it is fragile, and it is impossible to review in a pull request. You have come an enormous way from the fifteen manual steps of lesson 01-07, but the last stretch is still a script nobody wants to maintain.

That is exactly the problem solved by module 4, Docker Compose. Those fifty lines of imperative commands become a single compose.yaml file of about forty declarative lines, versioned in Git alongside the code, describing what the desired state of the platform is —four services with their images, variables, networks, volumes, limits, dependencies and policies— instead of the steps for getting there. The network and the volume create themselves; the startup order is declared with depends_on and its health condition instead of an until loop; and the whole platform comes up with docker compose up -d and goes down with docker compose down. One command, one file, and a new colleague who clones the repository and has Aurora Libros running on their machine in under a minute. The fifteen onboarding steps will become one.