Introduced in 0.3.15
While Dokku normally defaults to using Heroku buildpacks for deployment, you can also use Docker's native
Dockerfile system to define a container.
Dockerfile support is considered a power user feature. By using Dockerfile-based deployment, you agree that you will not have the same comfort as that enjoyed by buildpack users, and Dokku features may work differently. Differences between the two systems will be documented here.
This builder will be auto-detected in the following case:
Dockerfileexists in the root of the app repository.
Dokku will only select the
dockerfile builder if both the
pack builders are not detected and a Dockerfile exists. For more information on how those are detected, see the following links:
Switching from buildpack deployments¶
If an application was previously deployed via buildpacks and ports were customized, the following commands should be run prior to a deploy to ensure the Dockerfile ports are respected:
The previous method to perform this - via
docker-options:add - should be removed in favor of the
builder-dockerfile:set command outlined here.
When deploying a monorepo, it may be desirable to specify the specific path of the
Dockerfile file to use for a given app. This can be done via the
builder-dockerfile:set command. If a value is specified and that file does not exist in the app's build directory, then the build will fail.
For git push,
git:sync workflows, the
Dockerfile is extracted directly from the source code, respecting the configured
dockerfile-path property value.
The default value may be set by passing an empty value for the option:
dockerfile-path property can also be set globally. The global default is
Dockerfile, and the global value is used when no app-specific value is set.
The default value may be set by passing an empty value for the option.
Displaying builder-dockerfile reports for an app¶
Introduced in 0.25.0
You can get a report about the app's storage status using the
=====> node-js-app builder-dockerfile information Builder dockerfile computed dockerfile path: Dockerfile2 Builder dockerfile global dockerfile path: Dockerfile Builder dockerfile dockerfile path: Dockerfile2 =====> python-sample builder-dockerfile information Builder dockerfile computed dockerfile path: Dockerfile Builder dockerfile global dockerfile path: Dockerfile Builder dockerfile dockerfile path: =====> ruby-sample builder-dockerfile information Builder dockerfile computed dockerfile path: Dockerfile Builder dockerfile global dockerfile path: Dockerfile Builder dockerfile dockerfile path:
You can run the command for a specific app also.
You can pass flags which will output only the value of the specific information you want. For example:
Build-time configuration variables¶
For security reasons - and as per Docker recommendations - Dockerfile-based deploys have variables available only during runtime.
For users that require customization in the
build phase, you may use build arguments via the docker-options plugin. All environment variables set by the
config plugin are automatically exported during a docker build, and thus
--build-arg only requires setting a key without a value.
Once set, the Dockerfile usage would be as follows:
You may also set the argument as an environment variable
Building images with Docker BuildKit¶
If your Dockerfile is using Docker Engine's BuildKit (not to be confused with buildpacks), then the
DOCKER_BUILDKIT=1 environment variable needs to be set (unless you're using Docker Engine v24 or higher, which uses BuildKit by default). Additionally, complete build log output can be forced via
BUILDKIT_PROGRESS=plain. Both of these environment variables can be set as follows:
BuildKit directory caching¶
BuildKit implements the
RUN --mount option, enabling mount directory caches for
RUN directives. The following is an example that mounts debian packaging related directories, which can speed up fetching of remote package data.
Mount cache targets may vary depending on the tool in use, and users are encouraged to investigate the directories that apply for their language and framework.
You would adjust the cache directory for whatever application cache you have, e.g.
/root/.pnpm-store/v3 for pnpm,
$HOME/.m2 for maven, or
/root/.cache for golang.
Customizing the run command¶
By default no arguments are passed to
docker run when deploying the container and the
ENTRYPOINT defined in the
Dockerfile are executed. You can take advantage of docker ability of overriding the
CMD or passing parameters to your
$DOKKU_DOCKERFILE_START_CMD. Let's say for example you are deploying a base Node.js image, with the following
You can do:
To tell Docker what to run.
false will enable or disable Docker's image layer cache. Lastly, for more granular build control, you may also pass any
docker build option to
docker, by setting
Procfiles and multiple processes¶
Introduced in 0.5.0
See the Procfile documentation for more information on how to specify different processes for your app.
See the port management documentation for more information on how Dokku exposes ports for applications and how you can configure these for your app.