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.
5.4 KiB
0.39.0 Migration Guide
Changes
-
The buildpack
stackproperty has been split out of thebuildpacksplugin and into the two builder plugins that consume it. Previously a singlestackvalue set viabuildpacks:set-propertywas 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 viabuilder-herokuish:set <app> stack <value>(defaultgliderlabs/herokuish:latest-24), and the CNB builder is managed viabuilder-pack:set <app> stack <value>(defaultheroku/builder:24). Both support the--globalscope and exposestack,global-stack, andcomputed-stackkeys via their respective:reportcommands. -
The
buildpacks:set-property stackcommand 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 containsherokuish) are written tobuilder-herokuish, and all other values are written tobuilder-pack. Unsetting (buildpacks:set-property <app> stack) clears the value on both builders. -
The
--buildpacks-stack,--buildpacks-global-stack, and--buildpacks-computed-stackreport flags (and the correspondingstack,global-stack,computed-stackJSON keys) have been removed frombuildpacks:report. Usebuilder-herokuish:reportandbuilder-pack:reportinstead. Thebuildpacks:reportcommand continues to report the buildpackslist. -
The internal
buildpack-stack-nameplugin trigger has been removed. Each builder now reads its ownstackproperty directly during the build. -
Changing a builder's
stacknow clears that builder's build cache so the next deploy starts fresh. For herokuish this removes thecache-<app>Docker volume; for pack the nextpack buildruns with--clear-cache. -
The
dokkuDebian package now declarescoredns-docker (>= 0.6.0)as a hardDepends:.apt install dokkuandapt upgrade dokkupull it in automatically. The deb ships a default/etc/coredns/Corefilethat binds127.0.0.1:1053, serves thedocker.zone, and synthesizes<app>.<process-type>.dockerand<app>.dockerArecords from thecom.dokku.app-nameandcom.dokku.process-typelabels 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.sigilnow uses an nginxresolverdirective and a variable-basedproxy_passagainst<app>.<process-type>.dockerinstead of pinning the upstream to a literal IP. This is what addresses the long-standing post-reboot and post-apt-upgrade-dockerstale-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
offis the sentinel for disabling the resolver path. Settingdns-resolverto 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.sigiltemplates are unaffected by the change. The existingDOKKU_APP_<PROC>_LISTENERSvariable 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 itsproxy_passline to use the newDOKKU_APP_<PROC>_LISTENER_HOST,NGINX_DNS_RESOLVER, andNGINX_DNS_ZONEsigil 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> |