16f8b25bda
Add buildpacks:set --replace so callers can replace an app's complete ordered buildpack list in one command while preserving existing single-buildpack and --index behavior. Closes #8802
226 lines
9.2 KiB
Markdown
226 lines
9.2 KiB
Markdown
# 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.
|
|
|
|
```shell
|
|
# running for an app with no buildpacks specified
|
|
dokku buildpacks:list node-js-app
|
|
```
|
|
|
|
```
|
|
-----> test buildpack urls
|
|
```
|
|
|
|
```shell
|
|
# running for an app with two buildpacks specified
|
|
dokku buildpacks:list node-js-app
|
|
```
|
|
|
|
```
|
|
-----> test buildpack urls
|
|
https://github.com/heroku/heroku-buildpack-python.git
|
|
https://github.com/heroku/heroku-buildpack-nodejs.git
|
|
```
|
|
|
|
### Adding custom buildpacks
|
|
|
|
> 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:
|
|
|
|
```shell
|
|
dokku buildpacks:add node-js-app https://github.com/heroku/heroku-buildpack-nodejs.git
|
|
```
|
|
|
|
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.
|
|
|
|
```shell
|
|
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.
|
|
|
|
```shell
|
|
# 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.
|
|
|
|
```shell
|
|
dokku buildpacks:set node-js-app https://github.com/heroku/heroku-buildpack-ruby.git
|
|
```
|
|
|
|
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`.
|
|
|
|
```shell
|
|
# 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.
|
|
|
|
```shell
|
|
dokku buildpacks:set --index 99 node-js-app https://github.com/heroku/heroku-buildpack-ruby.git
|
|
```
|
|
|
|
### 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.
|
|
|
|
```shell
|
|
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:
|
|
|
|
```shell
|
|
dokku buildpacks:set --replace node-js-app https://github.com/heroku/heroku-buildpack-ruby.git
|
|
```
|
|
|
|
> [!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
|
|
|
|
> At least one of a buildpack or index must be specified
|
|
|
|
A single buildpack can be removed by name via the `buildpacks:remove` command.
|
|
|
|
```shell
|
|
dokku buildpacks:remove node-js-app https://github.com/heroku/heroku-buildpack-ruby.git
|
|
```
|
|
|
|
Buildpacks can also be removed by index via the `--index` flag. This flag is specified starting at a 1-index value.
|
|
|
|
```shell
|
|
dokku buildpacks:remove node-js-app --index 1
|
|
```
|
|
|
|
### Clearing all buildpacks
|
|
|
|
> 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.
|
|
|
|
```shell
|
|
dokku buildpacks:clear node-js-app
|
|
```
|
|
|
|
### Using a specific buildpack version
|
|
|
|
> 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:
|
|
|
|
```shell
|
|
# 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.
|
|
|
|
```shell
|
|
# 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:
|
|
|
|
```json
|
|
{
|
|
"buildpacks": [
|
|
{
|
|
"url": "heroku/python"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
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:
|
|
|
|
```shell
|
|
dokku buildpacks:report
|
|
```
|
|
|
|
```
|
|
=====> 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.
|
|
|
|
```shell
|
|
dokku buildpacks:report node-js-app
|
|
```
|
|
|
|
```
|
|
=====> node-js-app buildpacks information
|
|
Buildpacks list: https://github.com/heroku/heroku-buildpack-nodejs.git
|
|
```
|
|
|
|
You can pass flags which will output only the value of the specific information you want. For example:
|
|
|
|
```shell
|
|
dokku buildpacks:report node-js-app --buildpacks-list
|
|
```
|
|
|
|
## 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`) |
|