moebiusT7/book-ocr-studio
0
1<!doctype html>2<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Linux installation</title><style>body{margin:0;background:#f5f4ef;color:#18342f;font:17px/1.65 system-ui,sans-serif}main{max-width:900px;margin:auto;padding:35px 24px}a{color:#215947}h1{line-height:1.2}pre{background:#e8ebe3;padding:18px;overflow-x:auto;white-space:pre-wrap;overflow-wrap:anywhere}code{font-size:.88em}table{border-collapse:collapse;display:block;overflow:auto}td,th{padding:9px;border:1px solid #becbbf;text-align:left}nav{margin-bottom:32px}</style></head><body><main><nav><a href="index.html">Book OCR Studio</a> · <a href="install.html">Install</a> · <a href="benchmarks.html">Comparison</a> · <a href="release-notes.html">Release notes</a></nav><h1>Linux installation</h1>3 4<p>This beta targets Linux x86-64, Python 3.10 or 3.11, NVIDIA CUDA GPUs,5Google Chrome and Ollama. It is not a hosted OCR service. Model downloads6can require many gigabytes; model weights are not inside the source ZIP.7The standard installer prepares Gemma 12B automatically. The OCR-specific8C1 prompt and review workflow are already included in the application.9Install <a href="https://ollama.com/download/linux">Ollama</a> before running the standard installer.</p>10 11<h2>1. Python environment</h2>12 13<p>Install Python with its <code>venv</code> support using your operating system's package14manager. Extract the source archive to a writable directory. Then run:</p>15 16<pre><code>bash install.sh17</code></pre>18 19<p>If your default Python is newer, select an installed supported interpreter:</p>20 21<pre><code>BOOK_OCR_PYTHON=python3.11 bash install.sh22</code></pre>23 24<p>The installer creates <code>.venv</code> without inheriting system Python packages. It25refuses to modify an existing environment. A failed attempt may leave a26partial <code>.venv</code>; move that directory aside before retrying. It does not27install operating-system packages, Chrome or Ollama. After Python checks pass,28it downloads missing Gemma 12B weights using your installed Ollama executable.29Use <code>bash install.sh --skip-model</code> for Python dependencies only.30<code>requirements.txt</code> pins direct dependencies. On Python 3.10, the installer31also applies the tested transitive version snapshot in32<code>constraints-linux-py310.txt</code>. It is not an artifact-hash lock. Python 3.1133resolves transitive dependencies with pip and has not been installation-tested34for this release. The optional YomiToku environment resolves separately.</p>35 36<h2>2. CUDA and models</h2>37 38<p>Install a compatible NVIDIA driver and check <code>nvidia-smi</code>. The installer39uses PyTorch 2.10.0 from PyPI. Confirm CUDA actually works:</p>40 41<pre><code>.venv/bin/python scripts/check_install.py42</code></pre>43 44<p>If CUDA is unavailable, resolve the driver/PyTorch combination before OCR.45This build has not been qualified for CPU-only, AMD or Apple GPUs.</p>46 47<p>The standard installer invokes <code>scripts/setup_models.py</code>, which starts its own48short-lived loopback Ollama server and obtains <code>gemma4:12b-it-qat</code>. It does not49run inference or stop your existing Ollama server. Download progress is shown.50Existing matching tags in the chosen store are reused; their digest is recorded.51Tags can change upstream, so these are not permanently pinned weight artifacts.</p>52 53<p>Weights default to <code>models/</code> inside the extracted application directory.54<code>model-settings.json</code> records the resolved path and model digests; workers read55the same settings. Both are private and excluded from public packages.</p>56 57<p>If the download fails or you used <code>--skip-model</code>, retry just the model step:</p>58 59<pre><code>.venv/bin/python scripts/setup_models.py60</code></pre>61 62<p>Do not rerun the full installer against an existing <code>.venv</code>. Dependencies remain63installed after a failed model step. Retry can reuse Ollama's cached download data.</p>64 65<p>To add 26B (optional; does not change the UI's 12B default):</p>66 67<pre><code>.venv/bin/python scripts/setup_models.py --model gemma4:26b-a4b-it-qat68</code></pre>69 70<p>Select 26B in the app when needed. See <a href="benchmarks.html">BENCHMARKS.md</a> for the71limited historical comparison; there is no guaranteed whole-job speedup.</p>72 73<p>To reuse a different model store, set <code>BOOK_OCR_MODELS</code> to its directory before74running setup. The setup records that directory for subsequent workers. An75explicit environment override takes precedence. It must be readable and, for76new downloads, writable; no permissions are changed on an existing store.77Do not make model directories world-writable. For old installations without78settings, workers retain the legacy system-store fallback.</p>79 80<p>Read <a href="licenses.html">third-party terms</a> before downloading. Each exact81model retains its own license. Marker obtains its own weights on first OCR use;82those weights are separate from the Gemma setup step. C1 here is an OCR-specific83application workflow, not a new or fine-tuned model weight release.</p>84 85<h2>3. Start</h2>86 87<pre><code>bash run.sh88</code></pre>89 90<p>Open <code>http://127.0.0.1:8507/</code>. Use <code>BOOK_OCR_PORT</code> to change the UI port.91The optional extension opens port 8507 by default. The bridge uses port 8508.</p>92 93<p>For a synthetic source/export smoke test (no models):</p>94 95<pre><code>.venv/bin/python -m unittest discover -s public_tests -v96</code></pre>97 98<h2>4. Kindle: dedicated Chrome or optional extension</h2>99 100<p>Install Google Chrome separately. The <strong>Open Chrome for Kindle</strong> button uses101that browser through Playwright; it does not install another browser. Sign102in to Amazon in the opened window. The default profile is private local103<code>captures/chrome-profile/</code>, with no migration of any older profile. A fresh104installation therefore requires login again. Supported reader hosts are105<code>read.amazon.co.jp</code> and <code>read.amazon.com</code>; layouts may still need adaptation.</p>106 107<p>To connect an existing regular Chrome instead:</p>108 109<ol>110<li>Run <code>.venv/bin/python setup_chrome_bridge.py</code> locally.</li>111<li>Open <code>chrome://extensions</code>, enable Developer mode and load the112<code>chrome-extension/</code> directory. Review the debugger permission.</li>113<li>In the app, expand <strong>Connect your regular Chrome (optional)</strong> and click114<strong>Enable local Chrome bridge</strong>. Alternatively set115<code>BOOK_OCR_ENABLE_BRIDGE=1</code> before launching the app.</li>116<li>Open one Kindle book in Chrome, then start capture in the app.</li>117</ol>118 119<p>The bridge is not started for PDF-only use by default. Once enabled it runs120as a background process, including after the browser tab closes. To stop a121manually started bridge, use Ctrl+C; for an app-started bridge, identify the122exact <code>chrome_bridge.py</code> process in your process manager and terminate only123that process. Never use a broad command that kills all Python or Chrome124processes. Do not operate competing debugger extensions on the same tab.</p>125 126<p>The generated <code>.chrome-bridge-key</code> and <code>chrome-extension/config.js</code> are127private and excluded from the public package. Every fresh installation128generates its own key. To rotate it, stop the bridge, remove those two local129files, rerun setup and reload the extension. No key is supplied by this release.</p>130 131<h2>Optional YomiToku</h2>132 133<p>Read its CC BY-NC-SA terms and commercial licensing options in134<a href="licenses.html">THIRD<em>PARTY</em>NOTICES.md</a> first. If your use is permitted:</p>135 136<pre><code>bash install.sh --yomitoku137</code></pre>138 139<p>This creates a separate <code>.venv-yomitoku</code>. Select YomiToku explicitly in the140UI. Its weights are obtained separately. The default remains Marker.</p>141 142<h2>Privacy and troubleshooting</h2>143 144<p>Keep <code>jobs/</code>, <code>captures/</code>, browser profiles, logs and generated credentials145private. Use a source-only release builder when publishing modifications;146do not upload your working directory. Output to another AI service is a147separate user-controlled action.</p>148 149<p>When reporting an error, provide software versions and a synthetic150reproduction. Remove book text, screenshots, paths containing personal151details, cookies and secrets from logs before sharing.</p>152 153<h2>Optional vision API instead of local Gemma</h2>154 155<p>Gemma 4 remains the recommended default. To use a user-selected vision model156through the optional OpenAI-compatible connector, follow <a href="connectors.html">CONNECTORS.md</a>.157For this route, <code>bash install.sh --skip-model</code> skips Gemma preparation; local158OCR dependencies are still installed. You must prepare your chosen server159separately. A remote endpoint receives the page images and OCR text after160explicit enablement and may charge fees. API compatibility is not a quality161or completion guarantee.</p>162 163<h2>GPU process lifetime</h2>164 165<p>The app terminates its dedicated OCR and local Gemma processes after work or166on error. An independent supervisor watches an ownership pipe and cleans up the167owned process group if its caller disappears. This was tested with SIGKILL of168the caller, not SIGKILL of the supervisor itself or an unrecoverable driver fault.169Other applications and user-managed API servers are never stopped by this mechanism.170Closing the browser tab alone does not cancel an active background job; use the171job Stop control. Model review may finish its current request before stopping.</p>172<hr><p><a href="INSTALL.md" download>Download original text</a></p></main></body></html>173