Single-binary distribution: generated systemd unit, CLI bootstrap → SQLite config, tool preflight

kreeader-user commented

2026-07-17 21:08:19 -05:00

Owner

Goal

Single-binary distribution posture for the GitHub release: the server runs from one downloaded binary, generates (never installs) its own systemd unit, bootstraps from CLI args, and keeps all subsequent configuration in SQLite behind the Settings UI.

Decisions (Andrew, 2026-07-17)

systemd: generate only, never install. A service generate subcommand prints the unit to stdout by default; --write <path> writes it, offering the standard placements (/etc/systemd/system/, ~/.config/systemd/user/) as suggestions. It must never enable, start, or overwrite a package-manager-owned unit. Include the socket-activation variant (already supported by the server).
Bootstrap via CLI args, then DB. Initial parameters (port, db path, library paths, cache dir) come from CLI arguments on first run; anything passed as args is saved into AppSettings once the DB initializes. Subsequent config changes (args or Settings UI) also persist to the DB. Precedence: flags > DB > defaults. Existing installs: one-shot TOML import backfill (same pattern as librarian.backfilled) so /etc/kreeader keeps working and nothing is retyped.
First-run preflight warnings. On first run, warn on the CLI if tesseract is missing (it is exec'd, so this is detectable, and OCR features gate off via ocr.Available()). Warn if the CUDA OpenCV path is unavailable (CPU fallback engaged). NOTE the hard constraint: OpenCV itself is dynamically linked — if libopencv is absent the loader kills the process before main(), so no in-binary warning is possible for that case; mitigation is packaging-side (release-notes dependency list + container image).
Settings: manual tool paths. A Settings card for external-tool paths, starting with the tesseract binary path (validated when set); the same card is the future home for other Tier-1 external tools.

Repo & branch

kreeader-server. Library paths becoming runtime-editable is the largest sub-task (libpath roots are registered at startup; changing them live touches the relative-path machinery) and may deserve its own branch/issue when picked up.

Staged order

(1) settings precedence + TOML-import backfill, (2) library paths runtime-editable, (3) service generate subcommand + preflight warnings + tool-path Settings card, (4) per-platform release artifacts + container image.

Constraints

api/openapi.yaml is a hand-maintained contract: mirror any new/changed routes.
The ComicVine key in config.toml.example is intentionally committed — never scrub it.
Existing butcher deployment must upgrade cleanly (pacman-owned unit and /etc/kreeader untouched by default).

Acceptance criteria

Fresh box: download binary → run with -port/-library args → open web UI → everything else configured from Settings; args persisted to DB.
service generate prints a correct unit; --write honors the chosen placement; never enables/installs.
First run without tesseract prints a clear warning; Settings path field restores OCR without reinstalling.
Existing TOML-based install upgrades with zero behavior change.

## Goal Single-binary distribution posture for the GitHub release: the server runs from one downloaded binary, generates (never installs) its own systemd unit, bootstraps from CLI args, and keeps all subsequent configuration in SQLite behind the Settings UI. ## Decisions (Andrew, 2026-07-17) 1. **systemd: generate only, never install.** A `service generate` subcommand prints the unit to stdout by default; `--write <path>` writes it, offering the standard placements (`/etc/systemd/system/`, `~/.config/systemd/user/`) as suggestions. It must never enable, start, or overwrite a package-manager-owned unit. Include the socket-activation variant (already supported by the server). 2. **Bootstrap via CLI args, then DB.** Initial parameters (port, db path, library paths, cache dir) come from CLI arguments on first run; anything passed as args is saved into AppSettings once the DB initializes. Subsequent config changes (args or Settings UI) also persist to the DB. Precedence: flags > DB > defaults. Existing installs: one-shot TOML import backfill (same pattern as librarian.backfilled) so /etc/kreeader keeps working and nothing is retyped. 3. **First-run preflight warnings.** On first run, warn on the CLI if tesseract is missing (it is exec'd, so this is detectable, and OCR features gate off via ocr.Available()). Warn if the CUDA OpenCV path is unavailable (CPU fallback engaged). NOTE the hard constraint: OpenCV itself is dynamically linked — if libopencv is absent the loader kills the process before main(), so no in-binary warning is possible for that case; mitigation is packaging-side (release-notes dependency list + container image). 4. **Settings: manual tool paths.** A Settings card for external-tool paths, starting with the tesseract binary path (validated when set); the same card is the future home for other Tier-1 external tools. ## Repo & branch kreeader-server. Library paths becoming runtime-editable is the largest sub-task (libpath roots are registered at startup; changing them live touches the relative-path machinery) and may deserve its own branch/issue when picked up. ## Staged order (1) settings precedence + TOML-import backfill, (2) library paths runtime-editable, (3) `service generate` subcommand + preflight warnings + tool-path Settings card, (4) per-platform release artifacts + container image. ## Constraints - api/openapi.yaml is a hand-maintained contract: mirror any new/changed routes. - The ComicVine key in config.toml.example is intentionally committed — never scrub it. - Existing butcher deployment must upgrade cleanly (pacman-owned unit and /etc/kreeader untouched by default). ## Acceptance criteria - Fresh box: download binary → run with `-port`/`-library` args → open web UI → everything else configured from Settings; args persisted to DB. - `service generate` prints a correct unit; `--write` honors the chosen placement; never enables/installs. - First run without tesseract prints a clear warning; Settings path field restores OCR without reinstalling. - Existing TOML-based install upgrades with zero behavior change.

kreeader-user referenced this issue

2026-07-17 21:16:06 -05:00

Lite build: OpenCV as an optional dependency, capability-gated UI (no detection references in !opencv) #36

kreeader-user referenced this issue

2026-07-17 21:29:17 -05:00

Distributed tier build-out (consent granted 2026-07-17) #28

andrew referenced this issue from a commit

2026-07-18 18:25:04 -05:00

service: `service generate` subcommand + first-run preflight (#35)

andrew referenced this issue from a commit

2026-07-18 18:25:04 -05:00

Merge service generate + preflight (Opus agent, #35)

andrew referenced this issue from a commit

2026-07-19 15:09:52 -05:00

config: persist CLI knobs to AppSettings + one-shot TOML import (#35)

andrew referenced this issue from a commit

2026-07-19 15:09:52 -05:00

Merge args→AppSettings bootstrap + TOML import (Opus agent, #35)

kreeader-user commented

2026-07-19 15:25:40 -05:00

Author

Owner

All stages shipped and deployed (r329): service generate subcommand (stdout-first, --write/--user, never installs), first-run preflight warnings, CLI-args→AppSettings persistence with flags>DB>file>defaults precedence, one-shot TOML import (config.toml_imported.v1). Library paths now DB-resolvable. Verified live on butcher.

All stages shipped and deployed (r329): `service generate` subcommand (stdout-first, --write/--user, never installs), first-run preflight warnings, CLI-args→AppSettings persistence with flags>DB>file>defaults precedence, one-shot TOML import (config.toml_imported.v1). Library paths now DB-resolvable. Verified live on butcher.

kreeader-user closed this issue

2026-07-19 15:25:40 -05:00

andrew referenced this issue from a commit

2026-07-22 14:29:39 -05:00

service: `service generate` subcommand + first-run preflight (#35)

andrew referenced this issue from a commit

2026-07-22 14:29:39 -05:00

Merge service generate + preflight (Opus agent, #35)

andrew referenced this issue from a commit

2026-07-22 14:29:39 -05:00

config: persist CLI knobs to AppSettings + one-shot TOML import (#35)

andrew referenced this issue from a commit