Skip to content

fix(config): bind all defaulted keys to env vars; doc GOFLAGS=-tags=sqlite_fts5 for go install#95

Merged
aksOps merged 1 commit intomainfrom
fix/env-vars-and-fts5-doc
May 4, 2026
Merged

fix(config): bind all defaulted keys to env vars; doc GOFLAGS=-tags=sqlite_fts5 for go install#95
aksOps merged 1 commit intomainfrom
fix/env-vars-and-fts5-doc

Conversation

@aksOps
Copy link
Copy Markdown
Contributor

@aksOps aksOps commented May 4, 2026

Summary

Two bugs reported by a user installing v0.1.3 in a corporate environment.

Bug 1 — DOCSIQ_LLM_* env vars silently ignored without a config file.
Viper's AutomaticEnv() + Unmarshal() only reads env for keys that are explicitly bound via BindEnv (or already present in the merged config tree) — see Viper #761. Of all the LLM keys, only llm.call_timeout was bound, so DOCSIQ_LLM_PROVIDER, DOCSIQ_LLM_OLLAMA_*, DOCSIQ_LLM_AZURE_*, DOCSIQ_LLM_OPENAI_* were dropped for users without ~/.docsiq/config.yaml.

Fix: walk v.AllKeys() after all SetDefault calls and BindEnv each. The existing explicit BindEnv list stays — it documents the DOCSIQ_API_KEY alias for server.api_key and double-binds harmlessly.

Bug 2 — go install ...@v0.1.3 produces a binary that fails at runtime.
The user hits unable to open store: no such module: fts5 because mattn/go-sqlite3 only enables FTS5 with -tags=sqlite_fts5. The Makefile sets that tag; go install doesn't pick up Makefile tags. Docs-only fix: docs/getting-started.md now shows GOFLAGS='-tags=sqlite_fts5' go install ...@latest with a one-paragraph explanation of why the tag is required.

Files changed (3)

  • internal/config/config.gofor _, key := range v.AllKeys() { _ = v.BindEnv(key) } after defaults.
  • internal/config/config_test.go — new TestLoad_EnvOverridesLLM regression covering provider, Ollama, Azure, DataDir without a config file.
  • docs/getting-started.mdgo install line uses GOFLAGS='-tags=sqlite_fts5'; build-from-checkout go build line gains the tag for consistency.

Test plan

  • make vet clean.
  • make build clean.
  • make test green; new TestLoad_EnvOverridesLLM passes.
  • End-to-end smoke against a fresh binary on :37789 with DOCSIQ_LLM_PROVIDER=ollama DOCSIQ_LLM_OLLAMA_EMBED_MODEL=bge-m3 and no config file. Server log shows ⚙️ LLM provider initialised provider=ollama model=bge-m3 — confirms the env value flows into the resolved config.
  • Production server on :37777 was not touched.

Out of scope

  • Vendoring (go mod vendor) — v0.2.0.
  • Swapping mattn/go-sqlite3 for modernc.org/sqlite — separate, larger change.
  • The documents.file_hash UNIQUE collision on --force, case-sensitive /api/graph/neighborhood, community-finalize duplicate rows, and Upload SSE 202-vs-partial-fail status — all tracked separately.

🤖 Generated with Claude Code

…_fts5 for go install

Two product bugs reported against v0.1.3 from a corporate-firewall install.

1. DOCSIQ_LLM_* env vars silently ignored without a config file. Viper's
   AutomaticEnv() + Unmarshal() only reads env for keys that are either
   explicitly bound via BindEnv or already present in the merged config
   tree (Viper #761). Of all the LLM keys, only llm.call_timeout was
   explicitly bound, so DOCSIQ_LLM_PROVIDER, DOCSIQ_LLM_OLLAMA_*,
   DOCSIQ_LLM_AZURE_*, DOCSIQ_LLM_OPENAI_*, etc. were dropped on the
   floor for users without ~/.docsiq/config.yaml.

   Fix: after all SetDefault calls, iterate v.AllKeys() and BindEnv
   every one. The existing explicit BindEnv list stays — it documents
   the DOCSIQ_API_KEY shortcut alias for server.api_key and double-binds
   harmlessly. Adds TestLoad_EnvOverridesLLM as a regression test
   covering DOCSIQ_LLM_PROVIDER, the Ollama and Azure subtrees, and
   DOCSIQ_DATA_DIR — all without writing a config file.

2. go install github.com/RandomCodeSpace/docsiq@<ver> produces a binary
   that fails at runtime with "no such module: fts5" when opening any
   project store. mattn/go-sqlite3 only enables FTS5 when compiled with
   -tags=sqlite_fts5; the Makefile passes that, but go install does
   not pick up Makefile tags.

   Fix (docs only): docs/getting-started.md updated to document
   `GOFLAGS='-tags=sqlite_fts5' go install ...@latest` with an
   explanatory line on why the tag is non-negotiable. README's "Build
   from source" already shows the tag on `go build` and does not
   reference `go install`, so it stays. CONTRIBUTING.md does not
   reference `go install` either.

Verification:
- make vet, make build, make test all green.
- internal/config new test passes.
- End-to-end smoke: fresh binary on :37789 with DOCSIQ_LLM_PROVIDER=ollama
  DOCSIQ_LLM_OLLAMA_EMBED_MODEL=bge-m3 logs
  "LLM provider initialised provider=ollama model=bge-m3" without a
  config file — confirms env override path.
- Production server on :37777 untouched.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@aksOps aksOps enabled auto-merge (squash) May 4, 2026 04:15
@aksOps aksOps merged commit 50c6038 into main May 4, 2026
16 of 17 checks passed
@aksOps aksOps deleted the fix/env-vars-and-fts5-doc branch May 4, 2026 04:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant