docs: the FAQ called the .env method deprecated, not unsupported

"Deprecated" implies it used to work and might still. Nothing in LDR
loads a .env file, so a user following that line gets silence rather
than a warning. Point at env_configuration.md for the per-deployment
persistence mechanisms instead.

changelog.d/5649.misc.md

@@ -0,0 +1 @@
+Docs and `.env.template` now state clearly that LDR does not read a `.env` file — variables must be in the server process's environment — with a new per-deployment persistence table (compose `environment:`, `docker run -e`, systemd `EnvironmentFile=`, shell profile, Unraid template) in the environment-configuration guide.

docs/SearXNG-Setup.md

@@ -48,7 +48,8 @@ You have two ways to configure the SearXNG instance URL:
 
 1. **Environment Variable (Recommended for self-hosted instances)**:
    ```bash
-   # Add to your .env file or set in the server environment
+   # Set in the server process's environment (export / docker -e / compose
+   # environment: / systemd EnvironmentFile — LDR does not read a .env file)
    LDR_SEARCH_ENGINE_WEB_SEARXNG_DEFAULT_PARAMS_INSTANCE_URL=http://localhost:8080
 
    # Optional: Set custom delay between requests (in seconds)

docs/env_configuration.md

@@ -32,6 +32,27 @@ For example:
 
 For the complete list of all settings, their environment variable names, and default values, see [CONFIGURATION.md](CONFIGURATION.md).
 
+## Getting Variables Into LDR (and Making Them Persistent)
+
+LDR reads variables from the **server process's environment only — it does
+not load a `.env` file** (the bundled `.env.template` is a reference of
+available names, not a file LDR reads). The `export` examples on this page
+are ephemeral: they last until the shell session ends. To make a variable
+survive restarts and reboots, use the mechanism that matches your
+deployment:
+
+| Deployment | Persistent mechanism |
+|---|---|
+| Docker Compose | Add the variable under the service's `environment:` section in `docker-compose.yml` (this is how the bundled compose file sets the SearXNG URL) |
+| `docker run` | Pass `-e NAME=value` in the run command (persist it in whatever script/systemd unit starts the container) |
+| pip + systemd | Add `Environment="NAME=value"` lines to the unit, or point `EnvironmentFile=` at a root-owned key=value file |
+| pip + manual shell | Add the `export` lines to your shell profile (`~/.bashrc` or similar), or prefix the launch command: `NAME=value ldr-web` |
+| Unraid | Add the variable as a field on the container template |
+
+After changing a variable, restart LDR — values are read at startup (and on
+each settings lookup from the live environment, but a restart is the
+reliable way to guarantee every subsystem sees the change).
+
 ## API Keys
 
 API keys are best set using environment variables for security. Only the `LDR_` prefixed version is needed.

docs/faq.md

@@ -148,12 +148,14 @@ services:
 
 ### Where should I configure settings?
 
-**Important**: The `.env` file method is deprecated. Use the web UI settings instead:
+**Important**: LDR does not read a `.env` file. If you create one, nothing loads it — the bundled `.env.template` is a reference of available variable names, not a file LDR reads. Use the web UI settings instead:
 1. Run the web app: `python -m local_deep_research.web.app`
 2. Navigate to Settings
 3. Configure your preferences
 4. Settings are saved to the database
 
+To configure via environment variables instead, the variables must be present in the server process's environment. See [env_configuration.md](env_configuration.md) for how to set them persistently for your deployment (Docker Compose, `docker run`, systemd, shell profile, Unraid).
+
 For a complete reference of all settings, defaults, and environment variables, see [CONFIGURATION.md](CONFIGURATION.md).
 
 ### How do I download Ollama models in Docker?

docs/search-engines.md

@@ -123,7 +123,7 @@ result = quick_summary(
 - **Pricing**: Free tier available, paid plans for higher volume
 - **Configuration**:
   ```bash
-  # In .env file or web interface
+  # In the server environment or via the web interface
   LDR_SEARCH_ENGINE_TAVILY_API_KEY=your-key-here
   ```
 

src/local_deep_research/defaults/.env.template

@@ -5,6 +5,16 @@
 # Format: LDR_ + setting key with dots replaced by underscores, UPPERCASED
 # Example: app.debug -> LDR_APP_DEBUG
 #
+# IMPORTANT — how these variables reach LDR: this file is a REFERENCE of
+# available names. LDR does NOT read a .env file by itself; the variables
+# must be present in the server process's environment:
+#   - docker compose:  put them under the service's `environment:` section
+#   - docker run:      pass them with -e NAME=value
+#   - pip/bare metal:  `export NAME=value` before ldr-web (ephemeral), or
+#                      make it persistent via your shell profile or a
+#                      systemd unit's `EnvironmentFile=` pointing at a
+#                      root-owned copy of this file
+#
 # For most users, configure settings through the web UI at http://localhost:5000/settings
 
 # LLM API Keys