obsidian/wiki/concepts/docker-compose-cpu-limits-env.md

title	aliases	tags	sources	created	updated
Docker Compose CPU Limits Break Per Environment	docker-cpu-limits compose-cpu-env cpus-range-error	docker docker-compose deployment devops gotcha	daily/2026-04-29.md	2026-04-29	2026-04-29

Docker Compose CPU Limits Break Per Environment

Setting cpus: '4.0' in a prod docker-compose.yml and then running docker compose up on a server with only 2 CPUs causes a hard error. The fix is a per-environment compose override file that matches the target server's actual CPU count.

Key Points

• Error message: "range of CPUs is from 0.01 to 2.00" — appears at docker compose up, NOT at docker compose build
• The build succeeds silently; the failure only surfaces at container startup
• prod compose is the canonical config; environment-specific files override resource limits only
• Naming convention: docker-compose.{env}.yml (e.g. docker-compose.optical-dev.yml)

Details

The error occurs because Docker enforces CPU limits against the host's actual CPU count at container start time, not at image build time. A prod file with cpus: '4.0' is valid on a 4-core prod server but fails immediately on a 2-core staging server.

Prod compose (canonical):

services:
  ffmpeg-worker:
    deploy:
      resources:
        limits:
          cpus: '4.0'   # valid on 4-core prod
          memory: 8G

optical-dev override:

# docker-compose.optical-dev.yml
services:
  ffmpeg-worker:
    deploy:
      replicas: 0        # also disable heavy workers on this env
      resources:
        limits:
          cpus: '1.0'    # optical-dev has 2 CPUs — keep 1 for other services
          memory: 2G

Deploy command using override:

docker compose -f docker-compose.yml -f docker-compose.optical-dev.yml up -d

Pattern

File	Role
docker-compose.yml	Canonical config — prod values, all services defined
docker-compose.prod.yml	Prod-specific overrides (rarely needed if base IS prod)
docker-compose.optical-dev.yml	optical-dev overrides — reduced CPU/RAM, some services disabled
docker-compose.override.yml	Local dev — picked up automatically by Docker Compose

Related Concepts

• wiki/architecture/cloud-run-jobs-celery — why optical-dev uses this pattern for heavy workers
• wiki/architecture/optical-dev-server-deploy — optical-dev server constraints and deployment pattern

Sources

• daily/2026-04-29.md — session 20:29, cpus: '4.0' breaking on 2-CPU optical-dev server