Buildpacks Management¶
Note
Buildpacks commands apply to both herokuish and CNB-based builds
buildpacks:add [--index 1] <app> <buildpack> # Add new app buildpack while inserting into list of buildpacks if necessary
buildpacks:clear <app> # Clear all buildpacks set on the app
buildpacks:list <app> # List all buildpacks for an app
buildpacks:remove <app> <buildpack> # Remove a buildpack set on the app
buildpacks:report [<app>] [<flag>] # Displays a buildpack report for one or more apps
buildpacks:set [--index 1] <app> <buildpack> # Set new app buildpack at a given position defaulting to the first buildpack if no index is specified
buildpacks:set --replace <app> <buildpack> [<buildpack> ...] # Replace the entire ordered buildpack list with the specified buildpacks
Usage¶
Listing Buildpacks in Use¶
The buildpacks:list command can be used to show buildpacks that have been set for an app. This will omit any auto-detected buildpacks.
Adding custom buildpacks¶
Info
Please check the documentation for your particular buildpack as you may need to include configuration files (such as a Procfile) in your project root.
To add a custom buildpack, use the buildpacks:add command:
When no buildpacks are currently specified, the specified buildpack will be the only one executed for detection and compilation.
Multiple buildpacks may be specified by using the buildpacks:add command multiple times.
dokku buildpacks:add node-js-app https://github.com/heroku/heroku-buildpack-ruby.git
dokku buildpacks:add node-js-app https://github.com/heroku/heroku-buildpack-nodejs.git
Buildpacks are executed in order, may be inserted at a specified index via the --index flag. This flag is specified starting at a 1-index value.
# will add the golang buildpack at the second position, bumping all proceeding ones by 1 position
dokku buildpacks:add --index 2 node-js-app https://github.com/heroku/heroku-buildpack-golang.git
Overwriting a buildpack position¶
In some cases, it may be necessary to swap out a given buildpack. Rather than needing to re-specify each buildpack, the buildpacks:set command can be used to overwrite a buildpack at a given position.
By default, this will overwrite the first buildpack specified. To specify an index, the --index flag may be used. This flag is specified starting at a 1-index value, and defaults to 1.
# the following are equivalent commands
dokku buildpacks:set node-js-app https://github.com/heroku/heroku-buildpack-ruby.git
dokku buildpacks:set --index 1 node-js-app https://github.com/heroku/heroku-buildpack-ruby.git
If the index specified is larger than the number of buildpacks currently configured, the buildpack will be appended to the end of the list.
Replacing the entire buildpack list¶
To replace the complete ordered buildpack list in a single command, use the --replace flag. This is useful for tooling that needs to apply a full buildpack list atomically instead of running buildpacks:clear followed by multiple buildpacks:add calls.
dokku buildpacks:set --replace node-js-app https://github.com/heroku/heroku-buildpack-ruby.git https://github.com/heroku/heroku-buildpack-nodejs.git
The buildpacks are executed in the order they are specified, and the previous list is discarded. If any specified buildpack is invalid, the existing list is left unchanged.
A single buildpack may also be specified to replace the entire list with just that buildpack:
Note
The --replace flag cannot be combined with the --index flag. To remove all buildpacks, use the buildpacks:clear command instead of --replace with no buildpacks.
Removing a buildpack¶
Info
At least one of a buildpack or index must be specified
A single buildpack can be removed by name via the buildpacks:remove command.
Buildpacks can also be removed by index via the --index flag. This flag is specified starting at a 1-index value.
Clearing all buildpacks¶
Info
This does not affect automatically detected buildpacks, nor does it impact any specified BUILDPACK_URL environment variable.
The buildpacks:clear command can be used to clear all configured buildpacks for a specified app.
Using a specific buildpack version¶
Info
Always remember to pin your buildpack versions when using the multi-buildpacks method, or you may find deploys changing your deployed environment.
By default, builders will pin their vendored buildpacks, resulting in a consistent build result for your application. There may be occasions where the pinned version results in a broken deploy, or does not have a particular feature that is required to build your project. To use a more recent version of a given buildpack, the buildpack may be specified without a Git commit SHA like so:
# using the latest nodejs buildpack
dokku buildpacks:set node-js-app https://github.com/heroku/heroku-buildpack-nodejs
This will use the latest commit on the master branch of the specified buildpack. To pin to a newer version of a buildpack, a sha may also be specified by using the form REPOSITORY_URL#COMMIT_SHA, where COMMIT_SHA is any tree-ish git object - usually a git tag.
# using v87 of the nodejs buildpack
dokku buildpacks:set node-js-app https://github.com/heroku/heroku-buildpack-nodejs#v87
Specifying buildpacks via app.json¶
Buildpacks can also be specified in the app.json file at the root of your repository:
Buildpacks configured via buildpacks:add or buildpacks:set commands take precedence over those specified in app.json. If no buildpacks are configured via commands and app.json contains a buildpacks entry, those buildpacks will be used.
Shorthand buildpack references (e.g., heroku/python) are expanded to full GitHub URLs automatically.
Displaying buildpack reports for an app¶
You can get a report about the app's buildpacks status using the buildpacks:report command:
=====> node-js-app buildpacks information
Buildpacks computed stack: gliderlabs/herokuish:v0.7.0-22
Buildpacks global stack: gliderlabs/herokuish:latest-24
Buildpacks list: https://github.com/heroku/heroku-buildpack-nodejs.git
Buildpacks stack: gliderlabs/herokuish:v0.7.0-20
=====> python-sample buildpacks information
Buildpacks computed stack: gliderlabs/herokuish:latest-24
Buildpacks global stack: gliderlabs/herokuish:latest-24
Buildpacks list: https://github.com/heroku/heroku-buildpack-nodejs.git,https://github.com/heroku/heroku-buildpack-python.git
Buildpacks stack:
=====> ruby-sample buildpacks information
Buildpacks computed stack: gliderlabs/herokuish:latest-24
Buildpacks global stack: gliderlabs/herokuish:latest-24
Buildpacks list:
Buildpacks stack:
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:
Properties¶
Settable properties¶
These properties are managed via buildpacks:set-property (the legacy command name for this plugin).
Note
The Report flags column lists the CLI argument names accepted by buildpacks:report. The JSON keys emitted by buildpacks:report --format json are the same names with the leading --buildpacks- stripped (e.g. stack, global-stack, computed-stack). Legacy keys with the buildpacks- 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 |
|---|---|---|---|---|
stack |
app + global | none | --buildpacks-stack, --buildpacks-global-stack, --buildpacks-computed-stack |
Herokuish stack image used to compile the app (e.g. heroku/heroku:24) |