Files
dokku/docs/appendices/0.39.0-migration-guide.md
T
Jose Diaz-Gonzalez bf2795640c feat: make coredns-docker upstream resolution opt-in
The bundled `nginx.conf.sigil` keeps rendering IP-based upstreams unless `dns-resolver` is set, for example with `dokku nginx:set --global dns-resolver 127.0.0.1:1053`. Unsetting the property reverts to IP-based upstreams, replacing the previous `off` sentinel.
2026-11-06 20:51:33 -05:00

5.4 KiB

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.

  • The dokku Debian package now declares coredns-docker (>= 0.6.0) as a hard Depends:. apt install dokku and apt upgrade dokku pull it in automatically. The deb ships a default /etc/coredns/Corefile that binds 127.0.0.1:1053, serves the docker. zone, and synthesizes <app>.<process-type>.docker and <app>.docker A records from the com.dokku.app-name and com.dokku.process-type labels Dokku already stamps on every deployed container. The Docker image of Dokku ships coredns-docker preinstalled and runs it under runit on the same port.

  • The bundled nginx.conf.sigil can now use an nginx resolver directive and a variable-based proxy_pass against <app>.<process-type>.docker instead of pinning the upstream to a literal IP. This addresses the long-standing post-reboot and post-apt-upgrade-docker stale-vhost bug (#8313) - the rendered upstream re-resolves at request time via coredns-docker, so a host reboot or single-container restart no longer leaves nginx routing to a stale IP. This behavior is opt-in, and upstreams remain IP-based unless dns-resolver is set:

    dokku nginx:set --global dns-resolver 127.0.0.1:1053
    dokku proxy:build-config --all
    

    See the nginx documentation for details.

  • Three new nginx properties control the resolver path:

    • dns-resolver (default: none) - the address nginx talks to. Resolver-based upstreams are only rendered when this is set.
    • dns-resolver-timeout (default: 5s) - how long nginx waits for a DNS response before giving up and returning 502. The short default keeps clients from waiting on nginx's built-in 30s timeout when coredns-docker is unreachable.
    • dns-zone (default: docker) - the suffix appended to <app>.<process-type> when constructing the upstream hostname.

    All three can be set per app or globally via dokku nginx:set.

  • Vendored nginx.conf.sigil templates are unaffected by the change. The existing DOKKU_APP_<PROC>_LISTENERS variable continues to be populated with the IP-based listener list exactly as before, so templates that only reference it continue to render IP-based upstreams regardless of the new properties. To opt a vendored template into the resolver path, switch its proxy_pass line to use the new DOKKU_APP_<PROC>_LISTENER_HOST, NGINX_DNS_RESOLVER, NGINX_DNS_RESOLVER_TIMEOUT, and NGINX_DNS_ZONE sigil variables - see the nginx.conf.sigil reference for the exact snippet.

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>