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.
GPU server / cf-orch (managed deployments)
| Variable |
Default |
Description |
GPU_SERVER_URL |
(unset) |
Self-hosted GPU rig / cf-orch coordinator URL for GPU allocation. Preferred over CF_ORCH_URL. |
CF_ORCH_URL |
(unset) |
Legacy alias for GPU_SERVER_URL — still honoured if GPU_SERVER_URL is unset. |
CF_LICENSE_KEY |
(unset) |
License key for cf-orch authentication. When set and neither GPU_SERVER_URL nor CF_ORCH_URL is configured, defaults GPU_SERVER_URL to https://orch.circuitforge.tech (Paid+ tiers). |
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) |
