The OOM killer is not a bug in Docker. It is the kernel enforcing a limit you set — or forgot to set. On a 1–2 GB budget VPS, the difference between a stable container host and one that dies every few days is almost always three settings and a reliable way to read the exit code. This guide covers how to size memory limits from measured usage, how to spot the container that is quietly stealing pages from its neighbours, and what to change before you simply buy more RAM.<\/p>\n\n\n\n
When a container exits with code 137, you know two things: it received SIGKILL, and something decided it had to die. That something can be either of two different mechanisms, and the distinction matters because the fixes are not the same.<\/p>\n\n\n\n
--memory<\/code> limit. The kernel kills a process inside that cgroup, and only that cgroup is affected. docker inspect<\/code> shows OOMKilled: true<\/code>.<\/li>- Global OOM kill:<\/strong> the host ran out of memory overall and the kernel picked a victim, which may be any process. The killed process might be in a container that was behaving perfectly.<\/li><\/ul>\n\n\n\n
Code 137 also appears for a plain docker stop<\/code> that times out and escalates to SIGKILL, so always check OOMKilled<\/code> and the kernel log before you start tuning. On the host: dmesg -T | grep -i \"killed process\"<\/code> gives you the process name, the OOM score and, critically, whether it says cgroup out of memory<\/em> or Out of memory: Killed process<\/em> with no cgroup qualifier.<\/p>\n\n\n\nSizing Limits From Measured Usage<\/h2>\n\n\n\n
The common mistake is setting --memory<\/code> to a round number that feels safe, such as 512 MB for a PHP app or 1 GB for Postgres. Limits should be derived from a real measurement of resident set size (RSS) under your own peak load, with a known margin. Run the workload for a day without limits, then read the numbers:<\/p>\n\n\n\ndocker stats --no-stream<\/code> — the MEM USAGE \/ LIMIT column is instantaneous; watch it rather than snapshotting once.<\/li>docker stats --format '{{.Name}} {{.MemPerc}}'<\/code> in a loop, or a short while<\/code> loop appending to a file every 10 seconds for 24 hours.<\/li>cat \/sys\/fs\/cgroup\/system.slice\/docker-<id>.scope\/memory.peak<\/code> on cgroup v2 — the true high-water mark, which docker stats<\/code> will not show you.<\/li><\/ul>\n\n\n\nSet the limit at roughly 1.3–1.5× the observed peak, and never below the application’s startup footprint, because a container that cannot allocate during boot will crash-loop with no useful log. JVM and Node runtimes often peak at start before settling.<\/p>\n\n\n\nWorkload<\/th> Observed peak RSS<\/th> Suggested --memory<\/code><\/th>Suggested --memory-swap<\/code><\/th><\/tr><\/thead>Static nginx container<\/td> 25 MB<\/td> 64m<\/td> 128m<\/td><\/tr> Small Node.js API<\/td> 180 MB<\/td> 256m<\/td> 384m<\/td><\/tr> PHP-FPM + nginx (3 workers)<\/td> 420 MB<\/td> 640m<\/td> 768m<\/td><\/tr> PostgreSQL, small dataset<\/td> 380 MB<\/td> 512m<\/td> 1g<\/td><\/tr> Redis, cache only<\/td> 90 MB<\/td> 160m<\/td> 192m<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\nThose figures assume a total of 2 GB on the host. On a 1 GB VPS, cut worker counts rather than limits: a container that is genuinely allowed to use 640 MB out of 1 GB leaves nothing for the operating system, Docker daemon and page cache.<\/p>\n\n\n\n
The Settings That Matter More Than the Limit<\/h2>\n\n\n\n
A memory limit without swap control produces a hard kill at exactly the limit. That is intentional, but it converts a slow workload into a dead container. Adding a swap allowance changes the behaviour from “killed” to “slow”, which is a much better failure mode for anything user-facing.<\/p>\n\n\n\n
--memory-swap<\/code> set higher than --memory<\/code> gives the container swap. Setting it equal disables swap, which is the default-in-effect behaviour people do not expect.<\/li>--memory-reservation<\/code> is a soft limit applied before any kill happens.<\/li>--oom-kill-disable<\/code> should essentially never be used on a small VPS. It moves the kill from a contained process to a random host process, sometimes sshd<\/code>.<\/li>--kernel-memory<\/code> is removed in modern Docker and should not appear in current configurations.<\/li><\/ul>\n\n\n\nOn the host side, two kernel settings make the situation visible rather than fatal. vm.overcommit_memory=0<\/code> (the default) is the correct choice for Docker; setting it to 1 disables the accounting that lets the kernel refuse obviously impossible allocations. vm.swappiness=10<\/code> reduces pushing application pages to disk; avoid 0, which can trigger the OOM killer early.<\/p>\n\n\n\nFinding the Container That Caused It<\/h2>\n\n\n\n
With five containers on a 2 GB host, a global OOM kill is a whodunit. The kernel log gives you the victim, not the culprit. The repeatable method is:<\/p>\n\n\n\n
- Read
dmesg -T | grep -A5 \"oom-kill\"<\/code> and note the victim’s RSS and OOM score at the time of death.<\/li>- Compare that RSS with each container’s normal baseline from
docker stats<\/code>. A container using three times its usual memory is the culprit, even if another one was killed.<\/li>- Check which container has no
--memory<\/code> limit — in most incidents, that is the one.<\/li>- Look for timing patterns: kills clustered after a cron job, backup or crawler visit point at the culprit.<\/li><\/ol>\n\n\n\n
Then set the limit on the culprit. A container with a limit kills itself instead of the host, which means the rest of your stack stays up and your monitoring shows the true failure instead of a server that vanished.<\/p>\n\n\n\n
When Swap Is the Wrong Answer<\/h2>\n\n\n\n
Adding a 2 GB swap file to a 1 GB VPS is the most common first response to an OOM kill, and it usually makes things worse in a specific way: the container no longer dies, so you never learn that the workload is four times too large for the machine. Response times go from inconsistent to consistently terrible, because every request now touches disk.<\/p>\n\n\n\n
Swap is appropriate for cold pages and for smoothing brief spikes. It is not appropriate for a working set that exceeds RAM, and databases are the clearest case: InnoDB buffer pool pages swapped out under memory pressure produce latency in the hundreds of milliseconds per query. If vmstat 5<\/code> shows sustained si<\/code>\/so<\/code> activity while your application is idle, you are out of RAM, not out of tuning. Our breakdown of swap as a symptom of memory shortage<\/a> walks through the numbers behind that threshold.<\/p>\n\n\n\nA Reference Compose Configuration<\/h2>\n\n\n\n
The shape that works on a 2 GB host: limits on every service, reservations on the two that matter, log rotation, and a health check so Docker restarts a hung container rather than leaving it in place.<\/p>\n\n\n\n