From be3342f6474e343ce4a82d0f9a7e8d38d11ba31b Mon Sep 17 00:00:00 2001 From: marinom2 Date: Wed, 29 Jul 2026 16:08:57 +0300 Subject: [PATCH] docs: document worker.local.env, and that the search flag has a D Search configuration was documented nowhere in this repo - not the correct variable names, not where to put them, not that they are dropped on reinstall. An operator configuring it had to get the names from somewhere else, and at least one circulating spelling is wrong. The variable is SEARCH_ENABLED. `SEARCH_ENABLE` without the D is read by nothing: the worker starts cleanly, reports healthy, and never advertises search. There is no error and no log line, so the only way to notice is to observe that the capability never appears - which can take a while, and looks like a network problem rather than a typo. Verified against the shipped image rather than assumed: strings /bin/worker | grep -oE '\bSEARCH_[A-Z_]+\b' -> SEARCH_ENABLED `SEARCH_ENABLE` does not occur in the binary at all. The doc includes that command so the next reader can check their own image instead of trusting a file that may age badly. Also records the two things that cost real time when setting this up by hand: the container must run as root (session-keys.enc is root:root 0600, so the image's default appuser cannot read its own keystore and crash-loops), and this file alone is not a complete environment - without the installer's -e flags the worker exits with "CHAIN_ID is required" and four more. --- docs/WORKER_SETTINGS.md | 93 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 docs/WORKER_SETTINGS.md diff --git a/docs/WORKER_SETTINGS.md b/docs/WORKER_SETTINGS.md new file mode 100644 index 0000000..c9ef450 --- /dev/null +++ b/docs/WORKER_SETTINGS.md @@ -0,0 +1,93 @@ +# Worker settings (`worker.local.env`) + +Optional environment for the worker container that **survives a reinstall**. + +Before this existed, adding anything to the worker's environment meant editing the +container by hand, and the next install from the app threw it away — the run +command is generated fresh each time, so a manually-added `-e` flag disappeared +with the old container. Nothing failed loudly; a capability simply stopped being +advertised. + +## Where it goes + +``` +/../worker.local.env +``` + +For a default install that is: + +``` +~/lightchain-worker/worker.local.env +``` + +The installer applies it with `docker run --env-file` when the file exists, and +prints `▶ applying operator settings from …` so you can see it took effect. + +```bash +chmod 600 ~/lightchain-worker/worker.local.env # it will hold credentials +``` + +## Precedence + +This file is applied **before** the settings the installer manages +(`RPC_URL`, `CHAIN_ID`, `WORKER_REGISTRY_ADDRESS`, `AI_CONFIG_ADDRESS`, +`JOB_REGISTRY_ADDRESS`, `SUPPORTED_MODELS`, keystore paths, sortition config). + +That ordering is deliberate: those values win. A stale local file must not be able +to repoint `RPC_URL` and leave a worker talking to the wrong chain while still +looking healthy. + +Use it for capabilities and tuning, not for chain wiring. + +## Web search + +```ini +SEARCH_ENABLED=true +TAVILY_API_KEY=tvly-... +SEARCH_MAX_RESULTS=6 +SEARCH_TIMEOUT=30s +``` + +> ### ⚠️ The variable is `SEARCH_ENABLED`, with a **D** +> +> `SEARCH_ENABLE` (no D) is read by nothing. Set it and the worker starts +> cleanly, reports healthy, and **never advertises search** — a silent failure +> with no error to notice and no log line to grep for. +> +> Verify against whatever image you are running rather than trusting this file: +> +> ```bash +> docker exec lightchain-worker sh -c \ +> "strings /bin/worker | grep -oE '\bSEARCH_[A-Z_]+\b'" | sort -u +> ``` +> +> At the time of writing that returns exactly `SEARCH_ENABLED`, and +> `SEARCH_ENABLE` does not appear in the binary at all. + +## Applying a change + +The env of a running container cannot be altered, so it has to be recreated. +Re-running install from the app is the supported path and will pick the file up. + +## Verifying + +```bash +docker exec lightchain-worker env | grep -E '^SEARCH_|^TAVILY' +docker inspect lightchain-worker --format '{{.RestartCount}}' # want 0 +``` + +A non-zero and climbing restart count means the worker is crash-looping — check +`docker logs lightchain-worker`. A malformed line in this file (no `=`) will make +`docker run` reject the whole `--env-file`. + +## Two things that will bite + +**Run as root.** The installer starts the worker with `--user root`, and +`session-keys.enc` is written `root:root 0600`. Recreating the container without +`--user root` gives +`open /data/session-keys.enc: permission denied` in a restart loop. + +**Chain settings are not optional.** This file alone is not a complete +environment. Starting a container with only `--env-file worker.local.env` fails +with `CHAIN_ID is required` and four siblings — the installer's `-e` flags supply +those.