# Environment Variables

Copy `.env.example` to `.env` and configure as needed.

## Core

| Variable | Default | Description |
|----------|---------|-------------|
| `PAGEPIPER_DATA_DIR` | `data` | Directory for SQLite databases and uploads |
| `PAGEPIPER_WATCH_DIR` | _(unset)_ | Directory scanned for PDFs/EPUBs on demand |
| `SECRET_KEY` | _(required)_ | Random secret for internal signing |

## Ollama / BYOK

| Variable | Default | Description |
|----------|---------|-------------|
| `PAGEPIPER_OLLAMA_URL` | _(unset)_ | Ollama base URL, e.g. `http://localhost:11434`. Enables hybrid search and chat (BYOK gate — see below). |
| `PAGEPIPER_CHAT_MODEL` | `mistral:7b` | Ollama chat/completion model |
| `PAGEPIPER_EMBED_MODEL` | `nomic-embed-text` | Ollama embedding model — used for shelve-time embeddings only (`page_vecs`), not for search retrieval (see ColBERT below) |
| `PAGEPIPER_EMBED_DIMS` | `1024` | Embedding dimensions (must match `PAGEPIPER_EMBED_MODEL`) |

## Semantic search (ColBERT)

| Variable | Default | Description |
|----------|---------|-------------|
| `PAGEPIPER_COLBERT_MODEL` | `lightonai/Agent-ModernColBERT` | HuggingFace model used for hybrid search's semantic half — a late-interaction retriever, runs locally via `pylate`, no Ollama call required. Gated behind the same BYOK check as the rest of hybrid search (`PAGEPIPER_OLLAMA_URL` or `CF_ORCH_URL`/`GPU_SERVER_URL` must be set). |

**Note:** `page_vecs` (the sqlite-vec table populated at shelve time using `PAGEPIPER_EMBED_MODEL`) is no longer read by search or chat — retrieval was switched to the ColBERT index above (pagepiper#8). Shelving still computes and stores those embeddings for now; removing that redundant work is tracked as a follow-up.

## cf-orch (managed deployments)

| Variable | Default | Description |
|----------|---------|-------------|
| `CF_ORCH_URL` | _(unset)_ | cf-orch coordinator URL for GPU allocation |
| `CF_LICENSE_KEY` | _(unset)_ | License key for cf-orch authentication |
| `CF_APP_NAME` | `pagepiper` | Application identifier sent to cf-orch |

## License (cloud tier)

| Variable | Default | Description |
|----------|---------|-------------|
| `PAGEPIPER_HEIMDALL_URL` | _(unset)_ | Heimdall license server URL |
| `PAGEPIPER_HEIMDALL_TOKEN` | _(unset)_ | Admin token for license validation |

## Feature flags

| Variable | Default | Description |
|----------|---------|-------------|
| `PAGEPIPER_CHAT_FEEDBACK` | `false` | Enable thumbs up/down feedback UI on chat answers |
| `CLOUD_MODE` | `false` | Enable cloud-specific middleware (rate limiting, license checks) |