Migrate from environment variables to container labels
Author: rhansenCreated Jan 23, 2023Updated Aug 1, 2026
There have been some recently reported issues (and probably old issues) involving environment variable collisions between nginx-proxy and a proxied container (https://github.com/nginx-proxy/nginx-proxy/issues/2144#issuecomment-1401044235 and #2141). We should migrate away from environment variables on proxied containers and use labels instead.
We may also want to migrate the environment variables on the nginx-proxy container itself to labels, but the advantages are less clear. Originally posted in https://github.com/nginx-proxy/nginx-proxy/pull/1934#issuecomment-1401108904 and moved here:
Advantages of environment variables for the nginx-proxy container:
- Less work: we don't need to migrate them to labels like we do with the environment variables on proxied containers.
- Having distinct ways of configuring
nginx-proxyvs. the other containers might make configs more readable (environment variables are for the container's own use, labels are for use by a different container). - Consistency: Each container's own configuration comes from environment variables. (Labels are for external consumption.)
- Less ambiguity: Does the
com.github.nginx-proxy.nginx-proxy.foolabel apply to proxied containers, to thenginx-proxycontainer, or to both? With environment variables onnginx-proxyand labels on other containers, the setting's role is clear. (Though we could use label namespaces, such ascom.github.nginx-proxy.nginx-proxy.proxied.*for labels on proxied containers andcom.github.nginx-proxy.nginx-proxy.proxy.*for settings on thenginx-proxycontainer itself.) - Nested proxies: If
nginx-proxyused labels instead of environment variables for its own settings, then it would be difficult to add support for proxying to anothernginx-proxycontainer due to the likelihood of label collisions. (Namespacing could be used to avoid collisions but that might be more awkward than just using environment variables.)
Advantages of labels:
- Consistency: All
nginx-proxyconfiguration is done via labels (and include files). - Consistency: Setting
com.github.nginx-proxy.nginx-proxy.fooon thenginx-proxycontainer could set the default value of the container-specific label of the same name. - Less risk of collision with environment variables used by other code in the
nginx-proxycontainer (nginx itself, a custom nginx module added by the user, the shell,docker-gen, Docker API libraries, logging libraries, etc.). - Less pollution of the environment seen by various processes.
- It might be easier to prevent undesired disclosure of privacy- or security-sensitive values: Environment variables are normally copied to every spawned process, which makes it easier for an attacker to find a way to inspect the configuration. It should be easier to lock down access to the Docker socket to prevent such disclosure. (I haven't carefully studied the security implications so labels might actually increase the risk.)
Source: nginx-proxy/nginx-proxy