Skip to content

LOCAL_SETUP.md

Latest commit

 

History

History
110 lines (81 loc) · 3.54 KB

LOCAL_SETUP.md

File metadata and controls

110 lines (81 loc) · 3.54 KB
Raw

Local Setup and Daily Startup

One-Time Setup

Run this once after cloning the repository:

./setup-once.command

What it does:

  • Ensures PostgreSQL 15 binaries are available (Homebrew install if needed).
  • Creates .venv and installs Python dependencies.
  • Installs frontend npm dependencies.
  • Initializes project-local PostgreSQL data in .postgres_data on port 5433.
  • Creates lct_python_backend/.env from .env.example if missing.
  • Runs database migrations.

Daily Startup

Run this for day-to-day development:

./start.command

What it does:

  • Loads lct_python_backend/.env.
  • Cleans up stale backend/frontend processes from this repo.
  • Validates required local dependencies are present.
  • Starts local PostgreSQL if needed.
  • Runs alembic upgrade head.
  • Starts backend (uvicorn) and frontend (vite) with prefixed terminal logs.
  • Keeps both processes attached until Ctrl+C, then shuts both down.
  • Prints a quick STT endpoint status summary (legacy WS + known HTTP services).
  • Prints local LLM endpoint status ($LOCAL_LLM_BASE_URL/v1/models) and active mode.
  • Uses stable local defaults FRONTEND_PORT=43173 and BACKEND_PORT=43180, with env overrides when needed.

If migrations are already applied and Alembic history is temporarily inconsistent, skip migration execution for that run:

SKIP_MIGRATIONS=1 ./start.command

Override ports explicitly for one run:

FRONTEND_PORT=44173 BACKEND_PORT=44180 ./start.command

Shared STT Autostart

./start.command enables shared Parakeet autostart by default (STT_AUTOSTART=1) to support backend-owned STT routing.

Manual equivalent:

STT_AUTOSTART=1 STT_AUTOSTART_PROVIDER=parakeet ./start.command

Notes:

  • This reuses the sibling repository at ../parakeet-tdt-0.6b-v3-fastapi-openai.
  • The Parakeet container uses Docker volume parakeet-models, so model cache stays shared across projects.
  • If Docker/daemon/repo is unavailable, startup continues and logs a clear note.
  • To skip STT autostart for one run: STT_AUTOSTART=0 ./start.command.

Legacy Scripts Archive

The old startup/setup scripts were moved to:

scripts/legacy_commands/

Archived files:

  • setup-backend.command
  • setup-postgres-local.command
  • start-backend-local.command
  • start-backend.command
  • stop-postgres-local.command
  • start_server.sh

Local STT Reminder

Live audio transcription now runs through backend-owned STT routing. You need a reachable provider HTTP transcription URL in Settings (for example Parakeet http://localhost:5092/v1/audio/transcriptions). The legacy WS endpoint (:43001) is optional and no longer required for the default path.

Local LLM Reminder

Default local LLM endpoint is Tailscale LM Studio:

LOCAL_LLM_BASE_URL=http://100.81.65.74:1234

If an older config still points to localhost:1234, backend config merge rewrites it to the Tailscale base URL.

Logs and API Trace

  • Persistent backend log file: logs/backend.log
  • Terminal stream from start.command already prefixes backend/frontend logs.
  • Outbound STT + LLM call trace logging is enabled by default:
    • TRACE_API_CALLS=true
    • API_LOG_PREVIEW_CHARS=280
  • Frontend diagnostic logging is OFF by default (privacy-first). Opt in per namespace with VITE_LCT_DEBUG=api at build time, or at runtime via window.__lctDebug.enable("api") (sticky) / localStorage["lct:debug"]. Namespaces: api, graph, audio, stt, upload, import, dualview (comma-separate several, or * for all). See lct_app/src/utils/debug.js.