Files
dokku/docs/appendices/0.39.0-migration-guide.md
T
Jose Diaz-Gonzalez b5315de49b feat: add dns-resolver-timeout property defaulting to 5s
Adds a new `dns-resolver-timeout` global nginx property that controls how long nginx waits on the configured DNS resolver before giving up and returning 502. Without an explicit timeout nginx blocks on the resolver for its built-in 30s default, which means clients see hung requests instead of a fast 502 when coredns-docker is unreachable. The 5s default keeps failure-mode requests short while leaving headroom over a healthy local resolver round trip. The bundled `nginx.conf.sigil` emits `resolver_timeout {{ $.NGINX_DNS_RESOLVER_TIMEOUT }}` next to the existing `resolver` directive, and the outage-mode bats and docker-deploy tests now expect the curl call to complete inside that window.
2026-11-06 20:44:04 -05:00

5.7 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 now uses 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 is what 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. See the nginx documentation for details.

  • Three new global nginx properties control the resolver path:

    • dns-resolver (default: 127.0.0.1:1053) - the address nginx talks to.
    • 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 via dokku nginx:set --global <property> <value>.

  • The literal string off is the sentinel for disabling the resolver path. Setting dns-resolver to the empty string does not disable it - that deletes the property file and the new default (127.0.0.1:1053) re-engages. To revert to the legacy IP-based upstream block on hosts where coredns-docker cannot run (source/git installs, locally held coredns-docker package, postinst failures):

    dokku nginx:set --global dns-resolver off
    dokku proxy:build-config --all
    
  • 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 property defaults. 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>