CONTAO_ENV variable vs config file for enforcing production mode

Direct answers

1. Does CONTAO_ENV override localconfig.php? Yes. When CONTAO_ENV is set in the server environment it is read during Symfony kernel bootstrap and sets the kernel environment. The value in system/config/localconfig.php is loaded later for Contao‑specific settings and does not influence the kernel environment.
2. Where is var/cache resolved for a sub‑folder install? It is resolved relative to the Contao project root (kernel.project_dir), i.e., the directory that contains vendor/ and var/. It is not relative to the web document root (public/). No documented setting makes it document‑root relative; the path is project‑relative by design.
3. Does an explicit baseUrl in routing override automatic detection behind a trusted reverse proxy? Yes. Defining router.request_context.base_url (or contao.routing.base_url) overrides both Symfony’s automatic base‑path detection and any X-Forwarded-* headers, even when trusted proxies are configured.

Confirmed facts vs. likely explanation

Confirmed facts

• CONTAO_ENV is read at kernel bootstrap and takes precedence over any environment value stored in localconfig.php.
• var/cache uses kernel.project_dir as its base; the Contao core bundles (ContaoCoreBundle) configure paths via contao.paths in config/packages/contao.yaml.
• An explicit baseUrl in routing configuration overrides automatic detection and forwarded‑header detection.

Likely explanation

Because the kernel environment is decided before Contao‑specific configuration is loaded, relying on localconfig.php for mode enforcement is unreliable. The cache and upload directories are intentionally tied to the project root to keep them outside the web‑accessible public/ folder, which works the same whether the installation is in the document root or a subfolder. When a reverse proxy adds a prefix, setting baseUrl guarantees that generated URLs match the proxy’s public path, independent of forwarded‑header handling.

Steps for this case

1. Set CONTAO_ENV=prod in the server environment (e.g., via .env, web server config, or container). Do not rely on localconfig.php for mode.
2. Configure trusted proxies in config/packages/framework.yaml if the reverse proxy should forward X-Forwarded-* headers.
3. If the proxy adds a prefix (e.g., /contao), set router.request_context.base_url to that prefix in config/packages/routing.yaml (or via contao.routing.base_url).
4. Clear the cache after changing the environment or baseUrl: bin/console cache:clear --no-warmup followed by bin/console cache:warmup.

Missing diagnostic detail

To confirm whether the explicit baseUrl is actually needed, verify if trusted proxies are already configured and whether the X-Forwarded-Host or X-Forwarded-Prefix headers are being passed correctly. If they are, the baseUrl override may be redundant; if not, it is required.