How the Docker Compose calculator works

01 What the two settings do

The Compose file sets both under deploy.resources: the platform must stop the container from allocating more than the limit, and must guarantee it can allocate at least the reservation. Docker docs

• The limit becomes the container's hard memory limit (--memory). docker compose up applies it, and it takes precedence over a service-level mem_limit. Docker source
• The reservation becomes --memory-reservation: a soft limit, lower than the limit, that Docker enforces only when it detects contention or low memory on the host. Docker docs
• In Swarm, a service is only placed on a node with that much memory available to reserve, and a node's reservations can't add up to more than its memory. Docker docs

Docker's own advice is to test your application's memory needs before production; it publishes no formula. Docker docs That's what the average and peak you enter stand for.

02 Reservation and limit

reservation = average × (1 + request margin)                   rounded up to a whole M
limit       = max(peak × (1 + limit margin), reservation, 6M)   rounded up to a whole M

The margins come from the sensitivity, workload type and environment you choose; the sizing model explains them, and they are assumptions too.

Docker rejects a container whose memory limit is below its reservation, or below 6 MiB. So when the peak is so close to the average that the peak-based limit falls below the reservation, the limit is raised to the reservation. Docker source

Worked example

Average 410 MiB, peak 630 MiB, generic workload, medium sensitivity, production, 3 replicas:

A cache averaging 1000 MiB with a 1020 MiB peak, medium sensitivity, where the reservation decides the limit:

03 What the calculator writes

deploy:
  resources:
    limits:
      memory: 819M
    reservations:
      memory: 533M

• Memory is a byte value with a unit: b, k, m or g, with an optional b. Docker docs Compose reads it with Docker's RAM parser, which ignores case and counts in powers of 1024, so 819M is 819 MiB. Docker source
• The same values can go at service level, as mem_limit and mem_reservation. If both forms are set, they must agree. Docker docs

04 Swap

If the host has swap and memswap_limit isn't set, a container with a memory limit can use as much swap as that limit, so a 819M limit allows 1638M in total. Setting memswap_limit equal to the limit prevents any swap. Docker docs

The calculator leaves swap as Docker sets it: whether a service should swap or fail fast depends on the service, and the note under the result points it out. Assumption

05 Every warning, and why

06 What to paste

container_memory_working_set_bytes{name=~"myproject-api-[0-9]+"}

• This is cAdvisor's working set metric, a gauge in bytes. cAdvisor docs Its name label is the container's name. cAdvisor source
• Compose names a service's containers <project>-<service>-<number>, so the regex above matches every replica of the api service in the myproject project. Docker source A service with its own container_name needs that name instead. Assumption
• The working set leaves out file cache the kernel can reclaim, so it's closer to what the container really needs than total usage. Assumption A range query over a representative period (a week is a good default) gives the best average and peak.

The Kubernetes guide reads the same working-set metric, and also sizes a request from the average and a limit from the peak.

07 All assumptions in one place

Besides the margins of the shared sizing model:

Our default: a value we chose. Our reading: how we read documentation that isn't explicit. About your setup: something we take for granted about your data or cluster.

Values you can change

The calculator’s Advanced: margins and defaults section, closed by default, lets you replace these values when your setup differs. Each field’s “?” says how it moves the result; a value outside the range is used at its nearest end, and “Reset to defaults” puts them all back.

08 References

• Compose Deploy Specification — resources.limits and resources.reservations.
• Compose services — mem_limit, mem_reservation, memswap_limit.
• Compose file reference — byte value units.
• Resource constraints — --memory, --memory-reservation, swap, and testing before production.
• docker service create — how Swarm schedules by reservation.
• Compose source: create.go — how deploy.resources and mem_limit become container settings.
• Docker Engine source: daemon_unix.go — the 6 MiB minimum and limit ≥ reservation.
• go-units: size.go — how memory values are parsed.
• cAdvisor Prometheus metrics — container_memory_working_set_bytes.

← Back to the Docker Compose calculator