156 lines
4.7 KiB
Markdown
156 lines
4.7 KiB
Markdown
# Operations And Configuration
|
|
|
|
## Runtime Services
|
|
|
|
`docker-compose.yml` defines the runtime stack:
|
|
- `db` (Postgres 16, localhost-bound port `5432`)
|
|
- `redis` (Redis 7, localhost-bound port `6379`)
|
|
- `typesense` (Typesense 29, localhost-bound port `8108`)
|
|
- `api` (FastAPI backend, localhost-bound port `8000`)
|
|
- `worker` (RQ background worker)
|
|
- `frontend` (Vite UI, localhost-bound port `5173`)
|
|
|
|
## Named Volumes
|
|
|
|
Persistent volumes:
|
|
- `db-data`
|
|
- `redis-data`
|
|
- `dcm-storage`
|
|
- `typesense-data`
|
|
|
|
Reset all persisted runtime data:
|
|
|
|
```bash
|
|
docker compose down -v
|
|
```
|
|
|
|
## Operational Commands
|
|
|
|
Start or rebuild stack:
|
|
|
|
```bash
|
|
docker compose up --build -d
|
|
```
|
|
|
|
Stop stack:
|
|
|
|
```bash
|
|
docker compose down
|
|
```
|
|
|
|
Tail logs:
|
|
|
|
```bash
|
|
docker compose logs -f
|
|
```
|
|
|
|
Before running compose, provide explicit API tokens in your shell or project `.env` file:
|
|
|
|
```bash
|
|
export ADMIN_API_TOKEN="<random-admin-token>"
|
|
export USER_API_TOKEN="<random-user-token>"
|
|
```
|
|
|
|
Compose now fails fast if either token variable is missing.
|
|
|
|
## 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`
|
|
- `ADMIN_API_TOKEN`
|
|
- `USER_API_TOKEN`
|
|
- `PUBLIC_BASE_URL`
|
|
- `CORS_ORIGINS` (API service)
|
|
- `PROVIDER_BASE_URL_ALLOWLIST`
|
|
- `PROVIDER_BASE_URL_ALLOW_HTTP`
|
|
- `PROVIDER_BASE_URL_ALLOW_PRIVATE_NETWORK`
|
|
- `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_upload_files_per_request = 50`
|
|
- `max_upload_file_size_bytes = 26214400`
|
|
- `max_upload_request_size_bytes = 104857600`
|
|
- `max_zip_members = 250`
|
|
- `max_zip_depth = 2`
|
|
- `max_zip_member_uncompressed_bytes = 26214400`
|
|
- `max_zip_total_uncompressed_bytes = 157286400`
|
|
- `max_zip_compression_ratio = 120.0`
|
|
- `max_text_length = 500000`
|
|
- `processing_log_max_document_sessions = 20`
|
|
- `processing_log_max_unbound_entries = 400`
|
|
- `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:
|
|
|
|
```bash
|
|
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
|
|
- processing-log retention options (`keep_document_sessions`, `keep_unbound_entries`)
|
|
- provider configuration
|
|
- OCR, summary, and routing task settings
|
|
- predefined paths and tags
|
|
- handwriting-style clustering settings
|
|
|
|
Retention settings are used by worker cleanup and by `POST /api/v1/processing/logs/trim` when trim query values are not provided.
|
|
|
|
## Security Controls
|
|
|
|
- Privileged APIs are token-gated with bearer auth:
|
|
- `documents` endpoints: user token or admin token
|
|
- `settings` and `processing/logs` endpoints: admin token only
|
|
- Authentication fails closed when `ADMIN_API_TOKEN` is not configured.
|
|
- Provider base URLs are validated on settings updates and before outbound model calls:
|
|
- allowlist enforcement (`PROVIDER_BASE_URL_ALLOWLIST`)
|
|
- scheme restrictions (`https` by default)
|
|
- local/private-network blocking and per-request DNS revalidation checks for outbound runtime calls
|
|
- Upload and archive safety guards are enforced:
|
|
- multipart upload requires `Content-Length` and enforces file-count, per-file size, and total request size limits
|
|
- ZIP member count, per-member uncompressed size, total decompressed size, and compression-ratio guards
|
|
- Processing logs redact sensitive payload and text fields, and trim endpoints enforce retention caps from runtime config.
|
|
- Compose hardening defaults:
|
|
- host ports bind to `127.0.0.1` unless `HOST_BIND_IP` override is set
|
|
- `api`, `worker`, and `frontend` drop all Linux capabilities and set `no-new-privileges`
|
|
- backend and frontend containers run as non-root users by default
|
|
|
|
## 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
|