fix: validate nginx templates as the running nginx user

The wrapper config used to run `nginx -t` against an app's rendered `nginx.conf` declared no `user` directive, so nginx fell back to its compile-time default and chowned every `proxy_cache_path` directory to that user, including directories that already existed. On Debian and Ubuntu that default is `nobody`, so deploying an app shipping a custom `nginx.conf.sigil` took the running server's live cache directory away for the length of the build and turned every request the cache would serve into an HTTP 500, healing only once the deploy's own reload restored the ownership. The wrapper now declares the same `user` as the host's main nginx config, which is also exposed to custom `validate-config` templates as `$.NGINX_USER`.
This commit is contained in:
Jose Diaz-Gonzalez committed 2026-09-19 10:06:35 -04:00
1 parent b5ca1cd44d
commit 3423779f0f
10 files changed
+331 -16

No files matched your search

@@ -8,6 +8,8 @@ A custom `nginx.conf.sigil` is pre-validated at the start of every deploy, immed
Pre-validation is skipped when the proxy type is not `nginx` or when `disable-custom-config` is set to `true` for the app.
The wrapper declares the same `user` directive as the host's main nginx config, exposed to the wrapper template as `$.NGINX_USER`. This matters because `nginx -t` runs as `root` and chowns every directory the config registers - in particular any `proxy_cache_path` - to whichever user the config resolves to, whether or not that directory already exists. Without a matching `user`, validating a template that declares a `proxy_cache_path` would hand the running server's live cache directory to nginx's compile-time default user for the length of the build, and every request served from or stored in that cache would fail with a permission error until the deploy's own nginx reload restored the ownership.
### Custom nginx modules
Pre-validation runs `nginx -t` against a minimal wrapper config that does _not_ include the top-level `load_module` directives from the global `/etc/nginx/nginx.conf`. A `nginx.conf.sigil` that uses a directive provided by a dynamically loaded module - such as `image_filter`, provided by the [ngx_http_image_filter_module](https://nginx.org/en/docs/http/ngx_http_image_filter_module.html) - therefore fails pre-validation with an `unknown directive` error, even though `nginx -t` succeeds against the real server config where the module is loaded.
@@ -35,6 +37,7 @@ The custom `validate.conf.sigil`, which is the [default wrapper](https://github.
```
load_module modules/ngx_http_image_filter_module.so;
{{ if $.NGINX_USER }}user {{ $.NGINX_USER }};{{ end }}
events { worker_connections 768; }
http {
access_log off;
@@ -43,6 +46,8 @@ http {
}
```
A custom wrapper that omits the `user` line still has one injected before `nginx -t` runs, so wrappers written against older Dokku releases keep working, but declaring it explicitly documents the behavior and keeps the template self-contained.
The same override also governs the standalone `dokku nginx:validate-config` command, which renders the `validate-config` template as well.
## HTTP/2