Files
dokku/docs/appendices/0.39.0-migration-guide.md
T
Jose Diaz-Gonzalez 5241fd4be2 feat: resolve nginx upstreams via coredns-docker
Stops nginx from routing to stale container IPs after host reboots, Docker upgrades without live-restore, or runtime container restarts. The bundled `nginx.conf.sigil` can use an nginx `resolver` directive against the local `coredns-docker` socket and a variable-based `proxy_pass` keyed on `<app>.<process-type>.docker`, so the upstream is resolved at request time honoring DNS TTL. `coredns-docker` becomes a hard `Depends:` of the dokku deb and is bundled in the Docker image under runit. Closes #8313.
2026-11-06 20:43:16 -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 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.

  • Two new global nginx properties control the resolver path:

    • dns-resolver (default: 127.0.0.1:1053) - the address nginx talks to.
    • dns-zone (default: docker) - the suffix appended to <app>.<process-type> when constructing the upstream hostname.

    Both 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, 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>