From 2ef496f622687a766f9e6863e7c02014946e8c34 Mon Sep 17 00:00:00 2001 From: Sid Date: Wed, 3 Jun 2026 10:13:47 +0530 Subject: [PATCH] Document setup troubleshooting and ChromaDB conflict Fixes #375 Add setup troubleshooting notes for chromadb-client conflicts, LAN/Tailscale HTTPS exposure, optional dependencies, and clean up chromadb-client in the macOS starter when present. --- README.md | 35 +++++++++++++++++++++++++++++++++++ start-macos.sh | 9 +++++++++ 2 files changed, 44 insertions(+) diff --git a/README.md b/README.md index 4442507..d02c139 100644 --- a/README.md +++ b/README.md @@ -281,6 +281,41 @@ Local GPU *serving* of vLLM/SGLang needs Linux/WSL2; for a local model on Window Open `http://localhost:7000`, log in with the generated admin password, and configure everything else inside **Settings**. +## Troubleshooting & Advanced Setup + +### `chromadb-client` conflicts with embedded ChromaDB +If `chromadb-client` (the lightweight HTTP-only package) is installed alongside the full `chromadb` package, Odysseus starts but ChromaDB silently falls back to HTTP-only mode and fails. + +**Fix:** uninstall `chromadb-client` and force-reinstall the full package: +```bash +./venv/bin/pip uninstall chromadb-client -y +./venv/bin/pip install --force-reinstall chromadb +``` + +### HTTPS + LAN/Tailscale exposure +To expose Odysseus on a local network or Tailscale with HTTPS: +1. Change the bind address to `0.0.0.0` in `.env` (`APP_BIND=0.0.0.0` or `ODYSSEUS_HOST=0.0.0.0`). +2. Generate a locally-trusted cert for your LAN/Tailscale IPs using [mkcert](https://github.com/FiloSottile/mkcert): + ```bash + mkcert -install + mkcert -cert-file cert.pem -key-file key.pem 192.168.1.100 tailscale-ip + ``` +3. Run `uvicorn` with the generated certs: + ```bash + python -m uvicorn app:app --host 0.0.0.0 --port 7000 --ssl-certfile=cert.pem --ssl-keyfile=key.pem + ``` +4. Install the `mkcert` CA on any other device you want to access Odysseus from (e.g., for iOS, email the `rootCA.pem` to yourself, install the profile, and trust it in Certificate Trust Settings). + +### Optional Dependencies +`requirements-optional.txt` contains packages that unlock extra features. It is not installed by default. + +| Package | Feature unlocked | +|---------|-----------------| +| `faster-whisper` | Local speech-to-text (microphone -> text) via the "local" STT provider. | +| `duckduckgo-search` | DuckDuckGo as a search provider option. | +| `PyMuPDF` | PDF page rendering in the side viewer panel and form-filling. (Note: AGPL-3.0) | +| `markitdown` | Office/EPUB document text extraction (converts .docx/.xlsx/.pptx/.xls/.epub to Markdown). | + ## Security Notes Odysseus is a self-hosted workspace with powerful local tools: shell access, file uploads, model downloads, web research, email/calendar integrations, and API tokens. Treat it like an admin console. diff --git a/start-macos.sh b/start-macos.sh index 85a1b43..ca83b4c 100755 --- a/start-macos.sh +++ b/start-macos.sh @@ -139,6 +139,15 @@ echo "▶ Installing Python packages (first run downloads a few — can take a f # Not --quiet: this is the slow step, so show progress (and any real errors). "$VENV_PY" -m pip install -r requirements.txt +# chromadb-client (HTTP-only) conflicts with the full chromadb package. If +# it got installed (e.g., from an older requirements-optional.txt), remove +# it to prevent ChromaDB from silently failing in HTTP-only mode. +if "$VENV_PY" -m pip show chromadb-client >/dev/null 2>&1; then + echo "▶ Cleaning up conflicting chromadb-client package…" + "$VENV_PY" -m pip uninstall -y chromadb-client + "$VENV_PY" -m pip install --force-reinstall chromadb +fi + # 4. First-run setup: creates data dirs and prints an initial admin password # the first time (idempotent — does nothing if already set up). Suppress its # manual run hint — we launch the server ourselves just below.