From 20f2100d467acf8d6303ed7fc7d2c8c6429a5b71 Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Fri, 24 Apr 2026 02:54:06 -0400 Subject: [PATCH] docs: add 0.38.0 migration guide with nginx.conf.sigil update notes Custom nginx.conf.sigil templates that reference DOKKU_APP_WEB_LISTENERS may now receive an empty value when rendered for apps without running web processes. The migration guide documents how to handle this with a conditional in the template. --- docs/README.md | 1 + docs/appendices/0.38.0-migration-guide.md | 15 +++++++++++++++ 2 files changed, 16 insertions(+) create mode 100644 docs/appendices/0.38.0-migration-guide.md diff --git a/docs/README.md b/docs/README.md index 08ce6096d..b4e6d5c81 100644 --- a/docs/README.md +++ b/docs/README.md @@ -121,6 +121,7 @@ This documentation covers the installation, configuration, and usage of Dokku - ### Migration Guides +- [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.35.0](appendices/0.35.0-migration-guide.md) diff --git a/docs/appendices/0.38.0-migration-guide.md b/docs/appendices/0.38.0-migration-guide.md new file mode 100644 index 000000000..e547325ec --- /dev/null +++ b/docs/appendices/0.38.0-migration-guide.md @@ -0,0 +1,15 @@ +# 0.38.0 Migration Guide + +## Changes + +- Dokku now generates a minimal nginx configuration for apps without running `web` processes (undeployed apps, apps with no `web` process type, or apps with stopped web processes). This configuration returns `502 Bad Gateway` responses, ensuring the app's domain resolves and monitoring tools can detect non-200 status codes. The configuration is automatically replaced with the full proxy configuration once the app is deployed with running `web` processes. See the [nginx documentation](/docs/networking/proxies/nginx.md#nginx-configuration-for-undeployed-apps) for more details. +- Users with custom `nginx.conf.sigil` templates that reference `DOKKU_APP_WEB_LISTENERS` should be aware that this variable may now be empty when the template is rendered for apps without running web processes. Custom templates should handle this case gracefully, for example by using a conditional to serve an error page instead of proxying: + ``` + location / { + {{ if $.DOKKU_APP_WEB_LISTENERS }} + proxy_pass http://{{ $.APP }}-{{ $upstream_port }}; + {{ else }} + return 502; + {{ end }} + } + ```