Merge pull request #8493 from dokku/6760-build-empty-nginx-config-when-there-are-no-web-processes

Generate 502 config for apps without web listeners

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)

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 }}
+    }
+    ```

docs/networking/proxies/nginx.md

@@ -27,6 +27,21 @@ Nginx will proxy the requests in a [round-robin balancing fashion](http://nginx.
 > [!NOTE]
 > Due to how the plugin is implemented, if an app successfully starts up `web` containers but fails to deploy some other containers, nginx may eventually stop routing requests. Users should revert their code in these cases, or manually trigger `dokku proxy:build-config $APP` in order to ensure requests route to the new web containers.
 
+### Nginx Configuration for Undeployed Apps
+
+> [!IMPORTANT]
+> New as of 0.38.0
+
+When an app is created but not yet deployed, has no `web` process type, or has no running web processes, Dokku generates a minimal nginx configuration that returns `502 Bad Gateway` responses. This ensures that:
+
+- The app's domain resolves and returns a non-200 status code, allowing monitoring tools to detect the issue.
+- SSL certificate provisioning tools such as letsencrypt can function, as an nginx server is listening on the domain.
+- The `nginx.conf.d/` include directory is available for plugin customization.
+
+The 502 error page includes auto-retry JavaScript that will automatically reload the page when the application becomes available.
+
+Once the app is deployed with running `web` processes, the placeholder configuration is automatically replaced with the full proxy configuration.
+
 ### Starting nginx
 
 > [!IMPORTANT]