Drop Docker from deployment architecture

User's Proxmox LXC CTs run apps as plain venv + systemd services,
not containers. Updated spec sections 2, 6, and 9 to reflect a
bare-metal deployment: Postgres via apt, FastAPI app via uvicorn
under a systemd unit.
This commit is contained in:
Indiana
2026-07-20 07:02:14 +00:00
parent cadd74f0dd
commit 3634fed229

View File

@@ -22,7 +22,7 @@ Two machines on the local network:
- **Ollama box (10.30.20.107:11434)** — CPU-only, 64GB RAM, reachable over LAN via Ollama's REST API. Not managed by this repo's deployment; models are pulled there independently.
- **Cloudflare Tunnel** (managed on a separate machine, out of scope for this repo) — terminates HTTPS and exposes the app publicly by pointing at `http://<app-ct-ip>:7777`. The app itself never handles TLS/certs. Because visitors reach the site over the tunnel's HTTPS hostname, browser secure-context requirements (mic, WebUSB, DeviceMotion) are satisfied.
Two Docker containers: `app` (FastAPI + Piper + built frontend) and `postgres`. No separate nginx/reverse-proxy container needed — FastAPI serves the static frontend bundle directly.
No containers. Everything on the App CT runs as plain OS processes: a Python venv running the FastAPI app under `uvicorn`, managed as a systemd service (auto-restart, boot-start, logs via `journalctl`); Postgres installed directly via `apt`. FastAPI serves the built frontend static bundle directly — no separate reverse-proxy process needed.
**Known operational constraint:** Ollama is CPU-only and shared across all concurrent users. The backend implements a request queue (bounded concurrency, max queue depth) for all LLM calls. This is both a practical necessity and a thematic fit — queued requests render as "the spirits are gathering energy..." rather than a generic loading spinner.
@@ -66,7 +66,7 @@ Core tables:
## 6. Audio, TTS & Internationalization
Piper runs locally inside the `app` container, invoked per-utterance by the backend. Output is passed through an effects chain (static, bitcrush, pitch shift) before reaching the client, producing the classic degraded spirit-box vocal texture.
Piper runs locally as a process on the App CT, invoked per-utterance by the backend. Output is passed through an effects chain (static, bitcrush, pitch shift) before reaching the client, producing the classic degraded spirit-box vocal texture.
Frontend text is internationalized via react-i18next. Launch scope is **English + Spanish**, with the framework in place to add more languages later rather than attempting broad coverage at launch — both LLM reply quality and Piper voice quality vary by language, so scope stays deliberately tight until the core loop is proven. Selecting a language switches both the UI strings and the Piper voice model used for TTS; the backend also instructs the LLM to reply in the selected language.
@@ -86,7 +86,7 @@ Every hardware/permission dependency degrades gracefully rather than erroring:
## 9. Deployment
Docker Compose stack: `app` (FastAPI + Piper + built frontend, port 7777) and `postgres`. Configuration via `.env`: `OLLAMA_BASE_URL=http://10.30.20.107:11434`, database connection string, session secret. The Cloudflare Tunnel and Ollama model pulls (`ollama pull <fast-tier-model>`, `ollama pull <conversational-tier-model>`) are one-time setup steps on their respective external machines, outside this repo's scope.
No containers. On the App CT: Postgres installed via `apt` and running as its own system service; the FastAPI app (with Piper and the built frontend bundle) runs from a Python venv under `uvicorn`, managed by a systemd unit (`quantumancy.service`) for auto-restart and boot-start, with logs via `journalctl -u quantumancy`. Configuration via `.env` (loaded by the app, not committed): `OLLAMA_BASE_URL=http://10.30.20.107:11434`, database connection string, session secret. The Cloudflare Tunnel and Ollama model pulls (`ollama pull <fast-tier-model>`, `ollama pull <conversational-tier-model>`) are one-time setup steps on their respective external machines, outside this repo's scope.
## 10. Explicitly Out of Scope (this spec)