Merge pull request #9055 from dokku/9037-nginx-conf-sigil-pre-validation-chowns-proxy-cache-path-directories-to-nobody-breaking-the-running-nginx-for-the-whole-build

Validate nginx templates as the running nginx user
This commit is contained in:
Jose Diaz-Gonzalez authored and GitHub committed 2026-09-19 21:20:56 -04:00
commit f36512a19d
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
+1
View File
@@ -1346,6 +1346,7 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
- Invoked by: `nginx-vhosts#build-config`
- Arguments: `$APP $TEMPLATE_TYPE`
- The `TEMPLATE_TYPE` argument can be one of: `[app-config, hsts-config, validate-config]`
- The `validate-config` template can make use of the following variables: `$.NGINX_CONF $.NGINX_USER`
- Example:
```shell
+2
View File
@@ -123,6 +123,8 @@ App-supplied `nginx.conf.sigil` files are pre-validated automatically at the sta
The wrapper config used for validation does not include the top-level `load_module` directives from the global nginx config, so a `nginx.conf.sigil` that relies on a directive from a dynamically loaded module will fail this validation even when `nginx -t` passes against the real server config. See [Custom nginx modules](/docs/appendices/file-formats/nginx-conf-sigil.md#custom-nginx-modules) for how to supply a custom validation wrapper via the `nginx-app-template-source` trigger's `validate-config` template type.
The wrapper does declare the same `user` directive as the host's main nginx config, so that validating a template which declares a `proxy_cache_path` does not take the running server's cache directory away from the user its workers run as.
It may also be desired to validate an nginx config outside of the deployment process. To do so, run the `nginx:validate-config` command. With no arguments, this will validate all app nginx configs, one at a time. A minimal wrapper nginx config is generated for each app's nginx config, upon which `nginx -t` will be run.
```shell