From ac05dff73c0ffb3d6ae0f55e799df3ccb75f4cc3 Mon Sep 17 00:00:00 2001 From: Solanki Sumit <125974181+YAMRAJ13y@users.noreply.github.com> Date: Fri, 26 Jun 2026 23:54:02 +0530 Subject: [PATCH] docs(setup): add a self-host troubleshooting cookbook of common traps (#4834) ROADMAP "Self-host troubleshooting cookbook" asks to document the weird 30-second fixes that otherwise become 30-minute searches. Adds a "Common self-host traps" subsection under Troubleshooting covering: the UTF-8 BOM .env gotcha (app.py loads with utf-8-sig), macOS AirPlay holding port 7000 (the start script uses 7860), the plain-HTTP Tailscale/LAN clipboard limitation, self-hosted ntfy delivery (NTFY_BIND/NTFY_BASE_URL + the ntfy Android Instant-delivery toggle), Dovecot cleartext-auth on LAN mail stacks, and Radicale full-collection-URL sync. Docs only; grounded in existing repo behavior (.env.example NTFY_* block, app.py utf-8-sig loader, start-macos.sh port choice). Co-authored-by: Claude Opus 4.8 (1M context) --- docs/setup.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/setup.md b/docs/setup.md index 6978a263f..63a95f687 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -299,6 +299,16 @@ To expose Odysseus on a local network or Tailscale with HTTPS: ``` 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). +### Common self-host traps (30-second fixes) +A grab-bag of small gotchas that otherwise turn into long debugging sessions. + +- **`AUTH_ENABLED=false` is ignored / you're still forced to log in (Windows).** If you edited `.env` in Notepad it may have saved a UTF-8 **BOM**, turning the first key into `AUTH_ENABLED` so it is never matched. Odysseus loads `.env` with `encoding="utf-8-sig"` to tolerate a leading BOM, but the safe fix is to re-save `.env` as **UTF-8 without BOM** (VS Code: *Save with Encoding → UTF-8*). +- **macOS: the app isn't at `http://localhost:7000`.** macOS AirPlay Receiver usually holds port `7000`, so the macOS start script serves on **`7860`** instead — open `http://localhost:7860`. To use `7000`, free it (System Settings → General → AirDrop & Handoff → turn off *AirPlay Receiver*) and set `APP_PORT=7000`. +- **Copy buttons do nothing over a plain-HTTP Tailscale/LAN URL.** Browsers only expose the clipboard API (`navigator.clipboard`) on **secure origins** — HTTPS, or `localhost`. Over `http://100.x.y.z:7860` it is blocked. Serve over HTTPS (see *HTTPS + LAN/Tailscale exposure* above); `localhost` is exempt, so copy still works on the host itself. +- **Self-hosted ntfy reminders don't reach your phone.** Two things: (1) the bundled ntfy binds to loopback by default — to reach it from your phone set `NTFY_BIND` to your host/Tailscale IP and `NTFY_BASE_URL` to the same server URL in `.env`, then recreate the ntfy container (see the `NTFY_*` block in `.env.example`); (2) in the ntfy **Android** app, subscribe to the topic with **Instant delivery** enabled — non-`ntfy.sh` servers don't get instant push otherwise. +- **Local mail (Dovecot) login fails: "Plaintext authentication disallowed on non-encrypted connections."** Your IMAP/SMTP server is refusing cleartext auth over an unencrypted link. Prefer enabling TLS on the mail server; on a trusted LAN only, you can allow cleartext (Dovecot: `disable_plaintext_auth = no`). +- **Calendar/contacts (Radicale) won't sync.** Point Odysseus at the **full collection URL** with its trailing slash — e.g. `http://host:5232///` — not just the server root. Radicale shows this address for each calendar/address book in its web UI. + ### Optional Dependencies `requirements-optional.txt` contains packages that unlock extra features. It is not installed by default.