# 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:

```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
```

## 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:

```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
- 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