From 7234a62eb5e9f11d4d4f4d74d66668614c206a7a Mon Sep 17 00:00:00 2001
From: avi <avi@localhost>
Date: Tue, 15 Sep 2026 07:10:27 -0500
Subject: [PATCH] Debian support: verified build/packaging path + friend
 install guide
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- setup-standalone.sh: falls back to system python3 -m venv + pip when
  uv isn't installed (Debian/Ubuntu path; verified on clean bookworm).
- dist/Dockerfile.debian: debian:bookworm build env for :app:packageDeb
  (needs fakeroot + /usr/share/desktop-directories — both baked in; the
  dir gap made jpackage's postinst fail with exit 3 on minimal systems).
- dist/make-release.sh: clean source tarball from HEAD.
- INSTALL-debian.md: end-to-end install for friends (source tree must
  stay on disk — the app spawns the engine from it via SHONAR_REPO).

Verified on real Debian 12 in Docker: :app:packageDeb builds
shonar-desktop_0.1.0-1_amd64.deb, apt installs it, setup-standalone.sh
provisions the engine (venv+pip path, model fetch, boot smoke test),
and the packaged binary launches under Xvfb.
---
 .gitignore             |  2 ++
 INSTALL-debian.md      | 54 ++++++++++++++++++++++++++++++++++++++++++
 dist/Dockerfile.debian | 10 ++++++++
 dist/make-release.sh   | 10 ++++++++
 setup-standalone.sh    | 11 +++++++--
 5 files changed, 85 insertions(+), 2 deletions(-)
 create mode 100644 INSTALL-debian.md
 create mode 100644 dist/Dockerfile.debian
 create mode 100755 dist/make-release.sh

diff --git a/.gitignore b/.gitignore
index 0977100..e7cbd52 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,3 +8,5 @@ backend/__pycache__/
 *.pyc
 .dev-restart-flag
 models/hf-cache/
+dist/*.deb
+dist/*.tar.gz
diff --git a/INSTALL-debian.md b/INSTALL-debian.md
new file mode 100644
index 0000000..791cfd8
--- /dev/null
+++ b/INSTALL-debian.md
@@ -0,0 +1,54 @@
+# SHONAR Desktop — installing on Debian (12/13) or Ubuntu
+
+Everything runs locally on your machine. No accounts, no cloud, no
+telemetry. Audio, transcripts, and settings never leave your computer.
+
+There are two pieces: the **desktop app** (browse, transcribe, search)
+and the **transcription engine** (faster-whisper, bundled model — works
+offline after setup).
+
+## 1. Put the source tree where the app can find it
+
+The app auto-starts the bundled engine from the source folder, so keep
+the unpacked tarball around. Either:
+
+    mkdir -p ~/Projects && tar xzf shonar-desktop-*.tar.gz -C ~/Projects \
+      && mv ~/Projects/shonar-desktop-* ~/Projects/"Shonar Desktop"
+
+or extract anywhere and export `SHONAR_REPO=/that/path` (add it to
+`~/.profile`, or to the desktop launcher's Environment= line).
+
+## 2. Install the app
+
+Option A — .deb package (if you got `shonar-desktop_*.deb`):
+
+    sudo apt install ./shonar-desktop_0.1.0_amd64.deb
+    shonar-desktop
+
+Option B — run straight from the source tree (needs JDK 17, step 3):
+
+    cd ~/Projects/"Shonar Desktop" && ./launch-desktop.sh
+
+## 3. One-time setup
+
+    sudo apt install -y openjdk-17-jdk python3 python3-venv mpv
+    cd ~/Projects/"Shonar Desktop" && ./setup-standalone.sh
+
+This creates the engine's Python environment, vendors the whisper
+"base" model into `models/hf-cache` (one-time download, ~142 MB), and
+boots the engine once to prove it works.
+
+## 4. Run it
+
+Launch `shonar-desktop` (menu entry) or `./launch-desktop.sh`.
+The app starts the engine itself on first launch (takes a few seconds).
+Point "Choose folder…" at the folder holding your recordings and go.
+
+Notes
+- mpv is used for click-to-play from search results.
+- Summaries: if you run [Ollama](https://ollama.com) locally the app
+  uses it automatically; without it, transcription still works and
+  summaries are simply skipped.
+- Engine logs: `~/.config/shonar-desktop/engine.log`.
+- Wayland/Hyprland works; on X11 set nothing special.
+- Ctrl+= / Ctrl+- zooms the whole app; Ctrl+0 resets.
diff --git a/dist/Dockerfile.debian b/dist/Dockerfile.debian
new file mode 100644
index 0000000..f181819
--- /dev/null
+++ b/dist/Dockerfile.debian
@@ -0,0 +1,10 @@
+# Builds the SHONAR Desktop .deb on real Debian 12 and smoke-tests it.
+FROM debian:bookworm
+ENV DEBIAN_FRONTEND=noninteractive
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    openjdk-17-jdk dpkg-dev curl ca-certificates unzip git fakeroot \
+    python3 python3-venv python3-pip \
+    xvfb libasound2 libfreetype6 libfontconfig1 libgl1 libxrender1 \
+    && rm -rf /var/lib/apt/lists/* \
+    && mkdir -p /usr/share/desktop-directories
+WORKDIR /build
diff --git a/dist/make-release.sh b/dist/make-release.sh
new file mode 100755
index 0000000..41c56c5
--- /dev/null
+++ b/dist/make-release.sh
@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Build a shonar-desktop source release tarball from HEAD (no secrets, no
+# build junk, no runtime data). Friends unpack it and run setup-standalone.sh.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+VER=$(git describe --tags --always 2>/dev/null || echo dev)
+OUT="dist/shonar-desktop-$VER.tar.gz"
+git archive --format=tar --prefix="shonar-desktop/" HEAD \
+  | gzip > "$OUT"
+echo "wrote $OUT ($(du -h "$OUT" | cut -f1))"
diff --git a/setup-standalone.sh b/setup-standalone.sh
index 073c642..90fed05 100755
--- a/setup-standalone.sh
+++ b/setup-standalone.sh
@@ -6,8 +6,15 @@ cd "$(dirname "$0")"
 
 echo "==> backend venv (local, editable install of THIS backend)"
 if [ ! -x backend/.venv/bin/uvicorn ]; then
-  command -v uv >/dev/null || { echo "uv not found — install it: curl -LsSf https://astral.sh/uv/install.sh | sh"; exit 1; }
-  (cd backend && uv venv .venv --python 3.11 && uv pip install -p .venv/bin/python -e ".[dev,faster-whisper]")
+  if command -v uv >/dev/null; then
+    (cd backend && uv venv .venv --python 3.11 && uv pip install -p .venv/bin/python -e ".[dev,faster-whisper]")
+  else
+    # Plain Debian/Ubuntu path: system python3 (3.11 on bookworm) + venv + pip.
+    command -v python3 >/dev/null || { echo "python3 not found — install python3-venv"; exit 1; }
+    python3 -m venv backend/.venv || { echo "python3 -m venv failed — install the python3-venv package"; exit 1; }
+    backend/.venv/bin/pip install --upgrade pip >/dev/null
+    backend/.venv/bin/pip install -e "backend[dev,faster-whisper]"
+  fi
 else
   echo "    already present"
 fi