docs/OPERATIONS.md

Operations

Linux VM profile

For a 4-vCPU, 8-GiB, 20-GB VM, run one backend worker and one video export at a time. A second Gunicorn worker would create a second in-memory queue and can oversubscribe CPU/RAM.

python -m venv backend/.venv
source backend/.venv/bin/activate
pip install -r backend/requirements.txt
playwright install chromium
sudo apt-get install -y ffmpeg
cp backend/.env.example .env
gunicorn --workers 1 --timeout 900 --bind 127.0.0.1:5000 backend.wsgi:app

Set API_KEY in .env. For 4K exports, use the static/cut transition option when animation is unnecessary: the VFR path encodes one sparse still per hold instead of generating 14,400 repeated frames for an eight-minute 30-fps video. Transitions still require real frame generation around every animated span.

Persistence and retention

SQLite defaults to output/textbro.sqlite3, uses WAL mode, and imports legacy run/cache/history, client-queue, and ETA JSON on first access. Source JSON is retained for rollback but is no longer written.

On Linux, retention is enabled by default:

RETENTION_ENABLED=1
RETENTION_RUN_DAYS=30
RETENTION_MAX_RUNS=500
RETENTION_HISTORY_DAYS=30
RETENTION_CACHE_DAYS=7
RETENTION_MAX_CACHE_ENTRIES=100
RETENTION_OUTPUT_DAYS=30
RETENTION_MIN_FREE_DISK_GB=2

Expired output files are removed only from known generated-output directories. Files attached to active runs are protected. If free space drops below the configured floor, oldest unprotected artifacts are removed first.

Diagnostics

• GET /healthz: process liveness and active operation.
• GET /preflight: AI, FFmpeg/ffprobe, PowerPoint, and writable-folder checks.
• GET /openapi.json: OpenAPI 3.1 contract.
• GET /runs: persisted run summaries.
• GET /runs/<id>: stages, metrics, outputs, and event history.

FFmpeg progress is based on encoded media timestamps. Events include engine, encoded seconds, total seconds, speed, and ETA, so a 4K encode is not presented as an arbitrary frame-count task.

The browser Settings page stores Auto, FFmpeg, or MoviePy as the video engine preference. Auto uses FFmpeg first and MoviePy only as a compatibility fallback. Explicit selections are strict and fail with an actionable message when unavailable. Windows PowerPoint export remains unchanged. Each run stores the requested engine in settings and the actual engine in metrics.