MrSphay/odysseus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document setup troubleshooting and ChromaDB conflict

Browse Source 
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.
This commit is contained in:
Sid
2026-06-03 10:13:47 +05:30
committed by GitHub
parent 7d76fca21c
commit 2ef496f622
2 changed files with 44 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
README.md
View File

@@ -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.

9
start-macos.sh
View File

@@ -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.