Builder Management¶

New

Introduced in 0.24.0

builder:report [<app>] [<flag>]   # Displays a builder report for one or more apps
builder:set <app> <key> (<value>) # Set or clear a builder property for an app

Builders are a way of customizing how an app is built from a source, allowing users flexibility in how artifacts are created for later scheduling.

Usage¶

Builder selection¶

Dokku supports the following built-in builders:

builder-dockerfile: Builds apps using a Dockerfile via docker build. See the dockerfile builder documentation for more information on how this builder functions.
builder-herokuish: Builds apps with Heroku's v2a Buildpack specification via gliderlabs/herokuish. See the herokuish builder documentation for more information on how this builder functions.
builder-lambda: Builds AWS Lambda functions in an environment simulating AWS Lambda runtimes via lambda-builder. See the lambda builder documentation for more information on how this builder functions.
builder-null: Does nothing during the build phase. See the null builder documentation for more information on how this builder functions.
builder-pack: Builds apps with Cloud Native Buildpacks via the pack-cli tool. See the cloud native buildpacks builder documentation for more information on how this builder functions.

Builders run a detection script against a source code repository, and the first detected builder will be used to build the app artifact. The exception to this is when a Dockerfile is detected and the app is also able to use either herokuish or pack-cli for building, in which case one of the latter will be chosen.

Overriding the auto-selected builder¶

If desired, the builder can be specified via the builder:set command by specifying a value for selected. The selected builder will always be used.

dokku builder:set node-js-app selected dockerfile

The default value may be set by passing an empty value for the option:

dokku builder:set node-js-app selected

The selected property can also be set globally. The global default is an empty string, and auto-detection will be performed when no value is set per-app or globally.

dokku builder:set --global selected herokuish

Warning

Selecting a global builder will result in all applications using that builder unless a manual override is selected.

The default value may be set by passing an empty value for the option.

dokku builder:set --global selected

Changing the build directory¶

Warning

Please keep in mind that setting a custom build directory will result in loss of any changes to the top-level directory, such as the git.keep-git-dir property.

When deploying a monorepo, it may be desirable to specify the specific build directory to use for a given app. This can be done via the builder:set command. If a value is specified and that directory does not exist within the repository, the build will fail.

dokku builder:set node-js-app build-dir app2

The default value may be set by passing an empty value for the option:

dokku builder:set node-js-app build-dir

The build-dir property can also be set globally. The global default is empty string, and the global value is used when no app-specific value is set.

dokku builder:set --global build-dir app2

The default value may be set by passing an empty value for the option.

dokku builder:set --global build-dir

Skipping container and image cleanup¶

After a successful deploy, Dokku removes old containers and images that are no longer referenced by the app. On hosts where image rebuilds are expensive or where operators want to retain prior images for manual rollback, this cleanup can be disabled per-app or globally via the skip-cleanup property:

dokku builder:set node-js-app skip-cleanup true

The property can also be set globally:

dokku builder:set --global skip-cleanup true

The default behavior (cleanup enabled) may be restored by passing an empty value:

dokku builder:set node-js-app skip-cleanup

For backwards compatibility with bootstrap-time configuration, the DOKKU_SKIP_CLEANUP environment variable in /etc/environment or ~dokku/.dokkurc/* is still honored when the skip-cleanup property is unset. The property is the canonical interface and takes precedence when set.

Displaying builder reports for an app¶

You can get a report about the app's builder status using the builder:report command:

ShellOutput

dokku builder:report

=====> node-js-app builder information
       Builder build dir:          custom
       Builder computed build dir: custom
       Builder computed selected:  herokuish
       Builder global build dir:
       Builder global selected: herokuish
       Builder selected: herokuish
=====> python-sample builder information
       Builder build dir:
       Builder computed build dir:
       Builder computed selected: dockerfile
       Builder global build dir:
       Builder global selected: herokuish
       Builder selected: dockerfile
=====> ruby-sample builder information
       Builder build dir:
       Builder computed build dir:
       Builder computed selected: herokuish
       Builder global build dir:
       Builder global selected: herokuish
       Builder selected:

You can run the command for a specific app also.

ShellOutput

dokku builder:report node-js-app

=====> node-js-app builder information
       Builder selected: herokuish

You can pass flags which will output only the value of the specific information you want. For example:

dokku builder:report node-js-app --builder-selected

Custom builders¶

To create a custom builder, the following triggers must be implemented:

builder-build:
- arguments: BUILDER_TYPE APP SOURCECODE_WORK_DIR
- description: Creates a docker image named with the output of common#get_app_image_name $APP.
builder-detect:
- arguments: APP SOURCECODE_WORK_DIR
- description: Outputs the name of the builder (without the builder- prefix) to use to build the app.
builder-release:
- arguments: BUILDER_TYPE APP IMAGE_AG
- description: A post-build, pre-release trigger that can be used to post-process the image. Usually simply tags and labels the image appropriately.

Custom plugins names must have the prefix builder- or builder overriding via builder:set may not function as expected.

Builders can use any tools available on the system to build the docker image, and may even be used to schedule building off-server. The only current requirement is that the image must exist on the server at the end of the builder-build command, though this requirement may be relaxed in a future release.

For a simple example of how to implement this trigger, see builder-pack, which utilizes a cli tool - pack-cli - to generate an OCI image that is compatible with Docker and can be scheduled by the official scheduling plugins.

Properties¶

Settable properties¶

Note

The Report flags column lists the CLI argument names accepted by builder:report. The JSON keys emitted by builder:report --format json are the same names with the leading --builder- stripped (e.g. selected, global-selected, computed-selected). Legacy keys with the builder- prefix are also emitted during the 0.38.x deprecation window and will be removed in a future major release.

Property	Scope	Default	Report flags	Description
`build-dir`	app + global	none	`--builder-build-dir`, `--builder-global-build-dir`, `--builder-computed-build-dir`	Subdirectory within the repository to use as the build context
`selected`	app + global	none	`--builder-selected`, `--builder-global-selected`, `--builder-computed-selected`	Builder plugin to use; overrides automatic detection
`skip-cleanup`	app + global	`false`	`--builder-skip-cleanup`, `--builder-global-skip-cleanup`, `--builder-computed-skip-cleanup`	When `true`, leaves intermediate build artifacts in place after the build

Read-only flags¶

The following flags surface in builder:report but are not managed by builder:set:

Flag	Description
`--builder-detected`	Builder auto-selected for the app when `selected` is unset