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, the following commands should be run before a Dockerfile deploy will succeed:
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.
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:
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. 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
You can also customize the run command using a
Procfile, much like you would on Heroku or
with a buildpack deployed app. The
Procfile should contain one or more lines defining process types and associated commands.
When you deploy your app, a Docker image will be built. The
Procfile will be extracted from the image
(it must be in the folder defined in your
/app) and the commands
in it will be passed to
docker run to start your process(es). Here's an example
When you deploy this app the
web process will automatically be scaled to 1 and your Docker container
will be started basically using the command
docker run bin/run-prod.sh. If you want to also run
a worker container for this app, you can run
dokku ps:scale worker=1 and a new container will be
started by running
docker run bin/run-worker.sh (the actual
docker run commands are a bit more
complex, but this is the basic idea). If you use an
ENTRYPOINT in your
Dockerfile, the lines
Procfile will be passed as arguments to the
ENTRYPOINT script instead of being executed.
See the port management documentation for more information on how Dokku exposes ports for applications and how you can configure these for your app.