Skip to content

docs: document raising ulimit and vm.max_map_count for QuestDB in Docker - #477

Open
PedroHenrique0713 wants to merge 1 commit into
questdb:mainfrom
PedroHenrique0713:docs/docker-system-limits
Open

docs: document raising ulimit and vm.max_map_count for QuestDB in Docker#477
PedroHenrique0713 wants to merge 1 commit into
questdb:mainfrom
PedroHenrique0713:docs/docker-system-limits

Conversation

@PedroHenrique0713

Copy link
Copy Markdown
Contributor

What

Adds a "Raise system limits" section to the Docker deployment guide, documenting how to raise the two per-process OS limits QuestDB needs when running in a container: open files (ulimit -n) and memory-mapped areas (vm.max_map_count).

Why

On Docker, host ulimit settings do not propagate into the container, so a fresh container can log the warning reported in #370:

fs.file-max limit is too low [current=524288, recommended=1048576]

The Docker guide did not cover how to fix this, and the capacity planning guide only documents the systemd / limits.conf path, not the container one. This section fills that gap:

  • Open files: docker run --ulimit nofile=1048576:1048576, the Docker Compose ulimits equivalent, and default-ulimits in /etc/docker/daemon.json as a global alternative.
  • vm.max_map_count: set on the host via sysctl, since it is a host kernel setting shared with the container. This is the sibling limit QuestDB checks at startup, so I documented both together to match the startup check.

All values use the officially recommended 1048576 from the capacity planning guide, which the new section links to.

Closes #370

@PedroHenrique0713
PedroHenrique0713 force-pushed the docs/docker-system-limits branch from c884187 to 8f1eb21 Compare August 4, 2026 23:05
@PedroHenrique0713

Copy link
Copy Markdown
Contributor Author

Rebased on current main, so this is up to date and merges cleanly (one file, 53 additions, no deletions).

I rechecked that it is still needed: deployment/docker.md on main still says nothing about the two limits, and capacity-planning.md covers only the systemd, limits.conf and host sysctl paths. The container case is the gap, since host ulimits do not propagate into a container, which is what #370 reports. The section documents --ulimit nofile=1048576:1048576 (plus the Compose and daemon.json equivalents) and setting vm.max_map_count on the host, using the recommended 1048576 from capacity planning and linking back to it.

Thanks for the reviews this week. Is there anything you would like changed here before it can move forward?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Update /deployment/docker

1 participant