Merge pull request #8700 from dokku/migrate-stack-property-to-builder-herokuish
Split stack property into per-builder properties
This commit is contained in:
23 files changed
+449
-178
No files matched your search
@@ -123,6 +123,7 @@ This documentation covers the installation, configuration, and usage of Dokku -
|
||||
|
||||
### Migration Guides
|
||||
|
||||
- [0.39.0](appendices/0.39.0-migration-guide.md)
|
||||
- [0.38.0](appendices/0.38.0-migration-guide.md)
|
||||
- [0.37.0](appendices/0.37.0-migration-guide.md)
|
||||
- [0.36.0](appendices/0.36.0-migration-guide.md)
|
||||
|
||||
@@ -0,0 +1,21 @@
|
||||
# 0.39.0 Migration Guide
|
||||
|
||||
## Changes
|
||||
|
||||
- The buildpack `stack` property has been split out of the `buildpacks` plugin and into the two builder plugins that consume it. Previously a single `stack` value set via `buildpacks:set-property` was shared by both the herokuish and CNB (`pack`) builders, even though a herokuish stack image is not a valid CNB builder and vice versa. The herokuish stack is now managed via `builder-herokuish:set <app> stack <value>` (default `gliderlabs/herokuish:latest-24`), and the CNB builder is managed via `builder-pack:set <app> stack <value>` (default `heroku/builder:24`). Both support the `--global` scope and expose `stack`, `global-stack`, and `computed-stack` keys via their respective `:report` commands.
|
||||
- The `buildpacks:set-property stack` command is deprecated but continues to work. It emits a deprecation warning and forwards the value to the appropriate builder: values referencing a herokuish image (the value contains `herokuish`) are written to `builder-herokuish`, and all other values are written to `builder-pack`. Unsetting (`buildpacks:set-property <app> stack`) clears the value on both builders.
|
||||
- The `--buildpacks-stack`, `--buildpacks-global-stack`, and `--buildpacks-computed-stack` report flags (and the corresponding `stack`, `global-stack`, `computed-stack` JSON keys) have been removed from `buildpacks:report`. Use `builder-herokuish:report` and `builder-pack:report` instead. The `buildpacks:report` command continues to report the buildpacks `list`.
|
||||
- The internal `buildpack-stack-name` plugin trigger has been removed. Each builder now reads its own `stack` property directly during the build.
|
||||
- Changing a builder's `stack` now clears that builder's build cache so the next deploy starts fresh. For herokuish this removes the `cache-<app>` Docker volume; for pack the next `pack build` runs with `--clear-cache`.
|
||||
|
||||
### Stack property migrated to builder plugins
|
||||
|
||||
Existing `stack` values stored via `buildpacks:set-property` are migrated automatically the first time `dokku` runs the buildpacks plugin install step after the upgrade. Each per-app and global value is moved to `builder-herokuish` or `builder-pack` based on the same herokuish detection used by the deprecated command, and the old `buildpacks` value is removed. No manual action is required.
|
||||
|
||||
Going forward, configure the stack using the builder commands:
|
||||
|
||||
| Deprecated command | Replacement command |
|
||||
|---|---|
|
||||
| `dokku buildpacks:set-property <app> stack <herokuish-image>` | `dokku builder-herokuish:set <app> stack <herokuish-image>` |
|
||||
| `dokku buildpacks:set-property <app> stack <cnb-builder>` | `dokku builder-pack:set <app> stack <cnb-builder>` |
|
||||
| `dokku buildpacks:set-property --global stack <value>` | `dokku builder-herokuish:set --global stack <value>` / `dokku builder-pack:set --global stack <value>` |
|
||||
@@ -178,20 +178,11 @@ 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.
|
||||
@@ -215,11 +206,7 @@ dokku buildpacks:report node-js-app --buildpacks-list
|
||||
|
||||
### Settable properties
|
||||
|
||||
These properties are managed via `buildpacks:set-property` (the legacy command name for this plugin).
|
||||
The `buildpacks` plugin has no settable properties of its own. The list of buildpack URLs is managed via the `buildpacks:add`, `buildpacks:set`, `buildpacks:remove`, and `buildpacks:clear` commands.
|
||||
|
||||
> [!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`) |
|
||||
> [!WARNING]
|
||||
> The `buildpacks:set-property stack` command is deprecated as of 0.39.0. The `stack` property moved to the `builder-herokuish` and `builder-pack` plugins. Set it via `builder-herokuish:set <app> stack <value>` (herokuish) or `builder-pack:set <app> stack <value>` (CNB). The deprecated command still works but emits a warning and forwards the value to the appropriate builder based on whether the value references a herokuish image.
|
||||
@@ -100,14 +100,23 @@ dokku builder-pack:report
|
||||
Builder pack computed projecttoml path: project2.toml
|
||||
Builder pack global projecttoml path:
|
||||
Builder pack projecttoml path: project2.toml
|
||||
Builder pack computed stack: heroku/builder:24
|
||||
Builder pack global stack:
|
||||
Builder pack stack:
|
||||
=====> python-sample builder-pack information
|
||||
Builder pack computed projecttoml path: project.toml
|
||||
Builder pack global projecttoml path:
|
||||
Builder pack projecttoml path:
|
||||
Builder pack computed stack: heroku/builder:24
|
||||
Builder pack global stack:
|
||||
Builder pack stack:
|
||||
=====> ruby-sample builder-pack information
|
||||
Builder pack computed projecttoml path: project.toml
|
||||
Builder pack global projecttoml path:
|
||||
Builder pack projecttoml path:
|
||||
Builder pack computed stack: heroku/builder:24
|
||||
Builder pack global stack:
|
||||
Builder pack stack:
|
||||
```
|
||||
|
||||
The `projecttoml-path` and `global-projecttoml-path` keys hold the raw per-app and global value respectively, and are empty when nothing has been set. The `computed-projecttoml-path` key holds the effective value used at build time, falling back to the global value (where one has been set) and then to the built-in default of `project.toml`.
|
||||
@@ -138,32 +147,35 @@ project2.toml
|
||||
### Customizing the Buildpack stack builder
|
||||
|
||||
> [!IMPORTANT]
|
||||
> New as of 0.23.0
|
||||
> New as of 0.23.0. The `stack` property moved from the `buildpacks` plugin to the `builder-pack` plugin in 0.39.0.
|
||||
|
||||
The default stack builder in use by CNB buildpacks in Dokku is based on `heroku/builder:24`. Users may desire to switch the stack builder to a custom version, either to update the operating system or to customize packages included with the stack builder. This can be performed via the `buildpacks:set-property` command.
|
||||
The default stack builder in use by CNB buildpacks in Dokku is based on `heroku/builder:24`. Users may desire to switch the stack builder to a custom version, either to update the operating system or to customize packages included with the stack builder. This can be performed via the `builder-pack:set` command.
|
||||
|
||||
```shell
|
||||
dokku buildpacks:set-property node-js-app stack paketobuildpacks/build:base-cnb
|
||||
dokku builder-pack:set node-js-app stack paketobuildpacks/build:base-cnb
|
||||
```
|
||||
|
||||
The specified stack builder can also be unset by omitting the name of the stack builder when calling `buildpacks:set-property`.
|
||||
The specified stack builder can also be unset by omitting the name of the stack builder when calling `builder-pack:set`.
|
||||
|
||||
```shell
|
||||
dokku buildpacks:set-property node-js-app stack
|
||||
dokku builder-pack:set node-js-app stack
|
||||
```
|
||||
|
||||
A change in the stack builder value will execute the `post-stack-set` trigger.
|
||||
A change in the stack builder value flags the next build to run with `--clear-cache` so a stale pack cache is not reused.
|
||||
|
||||
Finally, stack builders can be set or unset globally as a fallback. This will take precedence over a globally set `DOKKU_CNB_BUILDER` environment variable (`heroku/builder:24` by default).
|
||||
|
||||
```shell
|
||||
# set globally
|
||||
dokku buildpacks:set-property --global stack paketobuildpacks/build:base-cnb
|
||||
dokku builder-pack:set --global stack paketobuildpacks/build:base-cnb
|
||||
|
||||
# unset globally
|
||||
dokku buildpacks:set-property --global stack
|
||||
dokku builder-pack:set --global stack
|
||||
```
|
||||
|
||||
> [!WARNING]
|
||||
> The `buildpacks:set-property stack` command is deprecated. It still works but emits a deprecation warning and forwards the value to `builder-pack` (when the value is a CNB builder) or `builder-herokuish` (when the value references a herokuish image).
|
||||
|
||||
### Specifying commands via Procfile
|
||||
|
||||
See the [Procfile documentation](/docs/processes/process-management.md#procfile) for more information on how to specify different processes for your app.
|
||||
@@ -175,3 +187,12 @@ See the [Procfile documentation](/docs/processes/process-management.md#procfile)
|
||||
| Property | Scope | Default | Report flags | Description |
|
||||
|---|---|---|---|---|
|
||||
| `projecttoml-path` | app + global | `project.toml` | `--builder-pack-projecttoml-path`, `--builder-pack-global-projecttoml-path`, `--builder-pack-computed-projecttoml-path` | Path within the app to the CNB `project.toml` manifest, relative to the build root |
|
||||
| `stack` | app + global | `heroku/builder:24` | `--builder-pack-stack`, `--builder-pack-global-stack`, `--builder-pack-computed-stack` | CNB builder image used to build the app (e.g. `paketobuildpacks/build:base-cnb`) |
|
||||
|
||||
### Internal properties
|
||||
|
||||
The following properties are recorded internally by the builder-pack plugin and are not exposed via `builder-pack:report`:
|
||||
|
||||
| Property | Scope | Description | Source |
|
||||
|---|---|---|---|
|
||||
| `clear-cache` | per-app | Transient flag set when the pack `stack` changes. The next `pack build` runs with `--clear-cache` and then the flag is deleted, ensuring a stack change does not reuse a stale pack cache | `plugins/builder-pack/subcommands/set` sets it on stack change; `plugins/builder-pack/builder-build` consumes and deletes it |
|
||||
@@ -46,32 +46,35 @@ dokku builder:set node-js-app selected herokuish
|
||||
### Customizing the Buildpack stack builder
|
||||
|
||||
> [!IMPORTANT]
|
||||
> New as of 0.23.0
|
||||
> New as of 0.23.0. The `stack` property moved from the `buildpacks` plugin to the `builder-herokuish` plugin in 0.39.0.
|
||||
|
||||
The default stack builder in use by Herokuish buildpacks in Dokku is based on `gliderlabs/herokuish:latest`. Typically, this is installed via an OS package which pulls the requisite Docker image. Users may desire to switch the stack builder to a custom version, either to update the operating system or to customize packages included with the stack builder. This can be performed via the `buildpacks:set-property` command.
|
||||
The default stack builder in use by Herokuish buildpacks in Dokku is based on `gliderlabs/herokuish:latest`. Typically, this is installed via an OS package which pulls the requisite Docker image. Users may desire to switch the stack builder to a custom version, either to update the operating system or to customize packages included with the stack builder. This can be performed via the `builder-herokuish:set` command.
|
||||
|
||||
```shell
|
||||
dokku buildpacks:set-property node-js-app stack gliderlabs/herokuish:latest
|
||||
dokku builder-herokuish:set node-js-app stack gliderlabs/herokuish:latest
|
||||
```
|
||||
|
||||
The specified stack builder can also be unset by omitting the name of the stack builder when calling `buildpacks:set-property`.
|
||||
The specified stack builder can also be unset by omitting the name of the stack builder when calling `builder-herokuish:set`.
|
||||
|
||||
```shell
|
||||
dokku buildpacks:set-property node-js-app stack
|
||||
dokku builder-herokuish:set node-js-app stack
|
||||
```
|
||||
|
||||
A change in the stack builder value will execute the `post-stack-set` trigger.
|
||||
A change in the stack builder value clears the herokuish build cache so the next deploy starts fresh.
|
||||
|
||||
Finally, stack builders can be set or unset globally as a fallback. This will take precedence over a globally set `DOKKU_IMAGE` environment variable (`gliderlabs/herokuish:latest-24` by default).
|
||||
|
||||
```shell
|
||||
# set globally
|
||||
dokku buildpacks:set-property --global stack gliderlabs/herokuish:latest
|
||||
dokku builder-herokuish:set --global stack gliderlabs/herokuish:latest
|
||||
|
||||
# unset globally
|
||||
dokku buildpacks:set-property --global stack
|
||||
dokku builder-herokuish:set --global stack
|
||||
```
|
||||
|
||||
> [!WARNING]
|
||||
> The `buildpacks:set-property stack` command is deprecated. It still works but emits a deprecation warning and forwards the value to `builder-herokuish` (when the value references a herokuish image) or `builder-pack` (otherwise).
|
||||
|
||||
### Allowing herokuish for non-amd64 platforms
|
||||
|
||||
> [!IMPORTANT]
|
||||
@@ -119,14 +122,23 @@ dokku builder-herokuish:report
|
||||
Builder herokuish computed allowed: false
|
||||
Builder herokuish global allowed:
|
||||
Builder herokuish allowed: false
|
||||
Builder herokuish computed stack: gliderlabs/herokuish:latest-24
|
||||
Builder herokuish global stack:
|
||||
Builder herokuish stack:
|
||||
=====> python-sample builder-herokuish information
|
||||
Builder herokuish computed allowed: true
|
||||
Builder herokuish global allowed:
|
||||
Builder herokuish allowed:
|
||||
Builder herokuish computed stack: gliderlabs/herokuish:latest-24
|
||||
Builder herokuish global stack:
|
||||
Builder herokuish stack:
|
||||
=====> ruby-sample builder-herokuish information
|
||||
Builder herokuish computed allowed: true
|
||||
Builder herokuish global allowed:
|
||||
Builder herokuish allowed:
|
||||
Builder herokuish computed stack: gliderlabs/herokuish:latest-24
|
||||
Builder herokuish global stack:
|
||||
Builder herokuish stack:
|
||||
```
|
||||
|
||||
The `allowed` and `global-allowed` keys hold the raw per-app and global value respectively, and are empty when nothing has been set. The `computed-allowed` key holds the effective value used at build time, falling back to the global value (where one has been set) and then to the built-in default (`true` on amd64, `false` otherwise).
|
||||
@@ -218,3 +230,4 @@ See the [buildpack management documentation](/docs/deployment/builders/buildpack
|
||||
| Property | Scope | Default | Report flags | Description |
|
||||
|---|---|---|---|---|
|
||||
| `allowed` | app + global | `true` | `--builder-herokuish-allowed`, `--builder-herokuish-global-allowed`, `--builder-herokuish-computed-allowed` | When `false`, the herokuish builder is skipped during builder detection for this app |
|
||||
| `stack` | app + global | `gliderlabs/herokuish:latest-24` | `--builder-herokuish-stack`, `--builder-herokuish-global-stack`, `--builder-herokuish-computed-stack` | Herokuish stack image used to compile the app (e.g. `gliderlabs/herokuish:latest`) |
|
||||
Reference in new issue
Block a user