ledgerdock/doc/operations-and-configuration.md

Operations And Configuration

Runtime Services

docker-compose.yml defines the runtime stack:

• db (Postgres 16, port 5432)
• redis (Redis 7, port 6379)
• typesense (Typesense 29, port 8108)
• api (FastAPI backend, port 8000)
• worker (RQ background worker)
• frontend (Vite UI, port 5173)

Named Volumes

Persistent volumes:

• db-data
• redis-data
• dcm-storage
• typesense-data

Reset all persisted runtime data:

docker compose down -v

Operational Commands

Start or rebuild stack:

docker compose up --build -d

Stop stack:

docker compose down

Tail logs:

docker compose logs -f

Backend Configuration

Settings source:

• Runtime settings class: backend/app/core/config.py
• API settings persistence: backend/app/services/app_settings.py

Key environment variables used by api and worker in compose:

• APP_ENV
• DATABASE_URL
• REDIS_URL
• STORAGE_ROOT
• PUBLIC_BASE_URL
• CORS_ORIGINS (API service)
• TYPESENSE_PROTOCOL
• TYPESENSE_HOST
• TYPESENSE_PORT
• TYPESENSE_API_KEY
• TYPESENSE_COLLECTION_NAME

Selected defaults from Settings (backend/app/core/config.py):

• upload_chunk_size = 4194304
• max_zip_members = 250
• max_zip_depth = 2
• max_text_length = 500000
• default_openai_model = "gpt-4.1-mini"
• default_openai_timeout_seconds = 45
• default_summary_model = "gpt-4.1-mini"
• default_routing_model = "gpt-4.1-mini"
• typesense_timeout_seconds = 120
• typesense_num_retries = 0

Frontend Configuration

Frontend runtime API target:

• VITE_API_BASE in docker-compose.yml frontend service

Frontend local commands:

cd frontend && npm run dev
cd frontend && npm run build
cd frontend && npm run preview

Settings Persistence

Application-level settings managed from the UI are persisted by backend settings service:

• file path: <STORAGE_ROOT>/settings.json
• endpoints: /api/v1/settings, /api/v1/settings/reset, /api/v1/settings/handwriting

Settings include:

• upload defaults
• display options
• provider configuration
• OCR, summary, and routing task settings
• predefined paths and tags
• handwriting-style clustering settings

Validation Checklist

After operational or configuration changes, verify:

• GET /api/v1/health is healthy
• frontend can list, upload, and search documents
• processing worker logs show successful task execution
• settings save or reset works and persists after restart