mirror of https://github.com/dokku/dokku.git synced 2026-05-18 05:05:46 +02:00

Files

Jose Diaz-Gonzalez 132f724841 feat: support resource limits on the build container

Adds a `docker-args-process-build` trigger to the resource plugin so
limits set via `dokku resource:limit --process-type build APP` are
applied during the build phase. Only `build.limit.*` properties are
read - defaults do not inherit, since builds typically need more memory
than runtime and a leaked tiny default would cause confusing OOM
failures. Reservations are never applied at build time. Allowed flags
are filtered per builder: herokuish gets cpu, memory, memory-swap, and
nvidia-gpu; dockerfile gets memory and memory-swap; pack, nixpacks,
railpack, lambda, and null emit nothing because their underlying CLIs
do not accept docker run resource flags. The dockerfile builder
whitelists the new memory flags and corrects pre-existing typos where
`--ssh` mapped to `--platform` and `--ulimit` mapped to `--tag`.

2026-04-29 03:42:10 -04:00

12 KiB

Raw Blame History

Resource Management

Important

New as of 0.15.0

resource:limit [--process-type <process-type>] [RESOURCE_OPTS...] <app>    # Limit resources for a given app/process-type combination
resource:limit-clear [--process-type <process-type>] <app>                 # Limit resources for a given app/process-type combination
resource:report [<app>] [<flag>]                                           # Displays a resource report for one or more apps
resource:reserve [--process-type <process-type>] [RESOURCE_OPTS...] <app>  # Reserve resources for a given app/process-type combination
resource:reserve-clear [--process-type <process-type>] <app>               # Reserve resources for a given app/process-type combination

The resource plugin is meant to allow users to limit or reserve resources for a given app/process-type combination.

Usage

By default, Dokku allows unlimited resource access to apps deployed on a server. In some cases, it may be desirable to limit this on a per-app or per-process-type basis. The resource plugin allows management of both resource "limits" and resource "reservations", where each resource request type has specific meaning to the scheduler in use for a given app.

Warning

The meaning of a values and it's units are specific to the scheduler in use for a given app. If a value is incorrect for a scheduler, this may result in containers failing to start correctly. If a scheduler does not support a given resource type combination, it will be ignored. All resource commands require an app rebuild or deploy in order to take effect.

Valid resource options include:

--cpu
--memory
--memory-swap
--network
--network-ingress
--network-egress
--nvidia-gpu

See the Supported Resource Management Properties section of the docker local scheduler documentation for more information on how each resource limit maps to Docker.

Resource reservations are applied only during the run and deploy phases of an application. Resource limits also apply during the build phase when explicitly configured against the build process type - see Build-time Resource Limits below.

Resource Limits

When specified and supported, a resource limit will ensure that your app does not go over the specified value. If this occurs, the underlying scheduler may either cap resource utilization, or it may decide to terminate and reschedule your process.

Resource limits may be set via the resource:limit command:

dokku resource:limit --memory 100 node-js-app

=====> Setting resource limits for node-js-app
       memory: 100

Multiple resources can be limited in a single call:

dokku resource:limit --cpu 100 --memory 100 node-js-app

=====> Setting resource limits for node-js-app
       cpu: 100
       memory: 100

Resources can also be limited on a per-process type basis. If specified, this will override any generic limits set for the app.

dokku resource:limit --cpu 100 --memory 100 --process-type worker node-js-app

=====> Setting resource limits for node-js-app (worker)
       cpu: 100
       memory: 100

A resource value can be individually cleared by setting the value to the special value clear.

dokku resource:limit --cpu clear node-js-app

=====> Setting resource limits for node-js-app
       cpu: cleared

Displaying Resource Limits

Running the resource:limit command without any flags will display the currently configured default app limits.

dokku resource:limit node-js-app

=====> resource limits node-js-app information [defaults]
       cpu:
       memory:
       memory-swap: 100
       network: 100
       network-ingress:
       network-egress:
       nvidia-gpu:

This may also be combined with the --process-type flag to see app limits on a process-type level. Note that the displayed values are not merged with the defaults.

dokku resource:limit --process-type web node-js-app

=====> resource limits node-js-app information (web)
       cpu: 100
       memory: 100
       memory-swap:
       network:
       network-ingress:
       network-egress:
       nvidia-gpu:

Build-time Resource Limits

Important

New as of 0.38.0

Resource limits may be applied to the build container by using the special build process type. This allows constraining memory and CPU usage during the build phase, which is otherwise unconstrained.

dokku resource:limit --memory 4g --process-type build node-js-app

=====> Setting resource limits for node-js-app (build)
       memory: 4g

Build-time limits are applied via the docker-args-process-build plugin trigger. They do not inherit from default (_default_) limits - only limits explicitly set against the build process type are applied at build time. This is intentional: build phases often require more memory than the runtime process, and silently inheriting a small runtime limit would cause confusing OOM failures.

Warning

Do not use build as a runtime process type in your Procfile. The build name is reserved by the resource plugin to scope limits to the build container, and using it as a Procfile entry will cause those limits to be applied to that runtime container as well.

Supported limits per builder:

Builder	`--cpu`	`--memory`	`--memory-swap`	`--nvidia-gpu`
herokuish	yes	yes	yes	yes
dockerfile	no	yes	yes	no
pack	no	no	no	no
nixpacks	no	no	no	no
railpack	no	no	no	no
lambda	no	no	no	no

Resource keys outside the supported set for a builder are silently ignored. Reservations (resource:reserve) are never applied at build time - only limits.

Clearing Resource Limits

In cases where the values are incorrect - or there is no desire to limit resources - resource limits may be cleared using the resource:limit-clear command.

dokku resource:limit-clear node-js-app

-----> Clearing resource limit for node-js-app

Defaults can also be cleared by leaving the app unspecified.

dokku resource:limit-clear

-----> Clearing default resource limits

Resource Reservations

When specified and supported, a resource reservation will ensure that your server has at least the specified resources before placing a given app's process. If there a resource exhaustion, future rebuilds and deploys may fail.

Resource reservations may be set via the resource:reserve command:

dokku resource:reserve --memory 100 node-js-app

=====> Setting resource reservation for node-js-app
       memory: 100

Multiple resources can be limited in a single call:

dokku resource:reserve --cpu 100 --memory 100 node-js-app

=====> Setting resource reservation for node-js-app
       cpu: 100
       memory: 100

Resources can also be limited on a per-process type basis. If specified, this will override any generic limits set for the app.

dokku resource:reserve --cpu 100 --memory 100 --process-type worker node-js-app

=====> Setting resource reservation for node-js-app (worker)
       cpu: 100
       memory: 100

A resource value can be individually cleared by setting the value to the special value clear.

dokku resource:reserve --cpu clear node-js-app

=====> Setting resource reservation for node-js-app
       cpu: cleared

Displaying Resource Reservations

Running the resource:reserve command without any flags will display the currently configured default app reservations.

dokku resource:reserve node-js-app

=====> resource reservation node-js-app information [defaults]
       cpu: 100
       memory: 100
       memory-swap:
       network:
       network-ingress:
       network-egress:
       nvidia-gpu:

This may also be combined with the --process-type flag to see app reservations on a process-type level. Note that the displayed values are not merged with the defaults.

dokku resource:reserve --process-type web node-js-app

=====> resource reservation node-js-app information (web)
       cpu: 100
       memory: 100
       memory-swap:
       network:
       network-ingress:
       network-egress:
       nvidia-gpu:

Clearing Resource Reservations

In cases where the values are incorrect - or there is no desire to reserve resources - resource reservations may be cleared using the resource:reserve-clear command.

dokku resource:reserve-clear node-js-app

-----> Clearing resource reservation for node-js-app