relata/.env.example

# Relata configuration.
#
# Copy to .env and adjust. Every value here has a working default; the file
# exists so the available settings are discoverable in one place.
#
#   cp .env.example .env
#
# .env must never be committed. It is listed in .gitignore.

# --- General ---------------------------------------------------------------

RELATA_ENV=development
# debug | info | warn | error
RELATA_LOG_LEVEL=info
# Structured JSON logs. Leave false for readable local output.
RELATA_LOG_JSON=false

# --- HTTP ------------------------------------------------------------------

# Relata binds to loopback by default. Listening on any other interface
# requires RELATA_ALLOW_EXTERNAL_BIND=true, so exposure is always deliberate.
RELATA_HTTP_ADDR=127.0.0.1:8080
RELATA_ALLOW_EXTERNAL_BIND=false

# Used for CSRF origin checks and for links printed by the CLI.
# Setting an https:// URL automatically enables Secure cookies.
RELATA_BASE_URL=http://127.0.0.1:8080

# Only enable when Relata genuinely sits behind a trusted reverse proxy:
# otherwise a forged X-Forwarded-For would defeat login rate limiting.
RELATA_TRUST_PROXY_HEADERS=false
RELATA_SECURE_COOKIES=false

RELATA_HTTP_READ_TIMEOUT=30s
# Must exceed RELATA_ANALYSIS_TIMEOUT: an answer is generated inside a request,
# and a shorter write timeout cuts the connection while the model is still working.
RELATA_HTTP_WRITE_TIMEOUT=360s
RELATA_HTTP_IDLE_TIMEOUT=90s
RELATA_HTTP_SHUTDOWN_TIMEOUT=20s
RELATA_MAX_REQUEST_BYTES=1048576
RELATA_METRICS_ENABLED=true

# --- MongoDB ---------------------------------------------------------------

RELATA_MONGO_URI=mongodb://127.0.0.1:27017
RELATA_MONGO_DATABASE=relata
RELATA_MONGO_TIMEOUT=10s

# In production, use a least-privilege account with readWrite on this database
# only, and put the credentials in the URI:
#   RELATA_MONGO_URI=mongodb://relata_app:PASSWORD@127.0.0.1:27017/relata?authSource=relata

# --- Qdrant ----------------------------------------------------------------

RELATA_QDRANT_URL=http://127.0.0.1:6333
RELATA_QDRANT_COLLECTION=relata_chunks
RELATA_QDRANT_TIMEOUT=15s
# Set when Qdrant requires an API key. Never commit a real value.
RELATA_QDRANT_API_KEY=

# --- AI providers ----------------------------------------------------------

RELATA_OLLAMA_BASE_URL=http://127.0.0.1:11434

# Pull these before first use:
#   ollama pull nomic-embed-text
#   ollama pull llama3.1:8b
RELATA_EMBEDDING_MODEL=nomic-embed-text
RELATA_ANALYSIS_MODEL=llama3.1:8b

# Must match the embedding model's output width. nomic-embed-text is 768.
# Changing this requires re-embedding the workspace.
RELATA_EMBEDDING_DIMENSIONS=768

# Set false to run without a language model. Ingestion, chunking, embedding,
# deterministic entity and claim extraction, relationship scoring and search
# all continue to work; only model-assisted analysis and generated answers stop.
RELATA_ANALYSIS_ENABLED=true

RELATA_EMBED_TIMEOUT=60s
# Generous because an 8B model on CPU takes tens of seconds per answer.
RELATA_ANALYSIS_TIMEOUT=300s
RELATA_EMBED_BATCH_SIZE=16
RELATA_AI_MAX_RETRIES=3
RELATA_AI_RETRY_BASE_DELAY=500ms
RELATA_AI_RETRY_MAX_DELAY=8s
RELATA_AI_MAX_OUTPUT_TOKENS=2048

# --- Uploads and limits ----------------------------------------------------

RELATA_UPLOAD_DIR=./data/uploads
RELATA_MAX_UPLOAD_BYTES=26214400
RELATA_MAX_EXTRACTED_TEXT_BYTES=2097152
RELATA_MAX_JSON_DEPTH=20
RELATA_MAX_METADATA_KEYS=40
RELATA_MAX_METADATA_VALUE_LEN=2000
RELATA_MAX_TITLE_LEN=300
RELATA_PROCESSING_TIMEOUT=10m
RELATA_MAX_CONCURRENT_INGEST=4

# --- Chunking --------------------------------------------------------------

RELATA_CHUNK_MAX_CHARS=1800
RELATA_CHUNK_TARGET_CHARS=1100
RELATA_CHUNK_MIN_CHARS=200
RELATA_CHUNK_OVERLAP_CHARS=120
RELATA_MAX_CHUNKS_PER_ITEM=400
# Documents smaller than this are never split.
RELATA_CHUNK_MIN_SPLIT_CHARS=900

# --- Background workers ----------------------------------------------------

RELATA_WORKERS_ENABLED=true
RELATA_WORKER_COUNT=3
# Concurrent AI calls, independent of worker count. Raise only if the model
# host can take it.
RELATA_AI_CONCURRENCY=2
RELATA_WORKER_POLL_INTERVAL=1s
RELATA_JOB_LEASE_DURATION=2m
# Must be shorter than the lease, or a running job would lose it.
RELATA_JOB_HEARTBEAT=30s
RELATA_JOB_MAX_ATTEMPTS=4
RELATA_JOB_TIMEOUT=8m

# --- Search ----------------------------------------------------------------

RELATA_SEARCH_VECTOR_CANDIDATES=60
RELATA_SEARCH_LEXICAL_CANDIDATES=60
RELATA_SEARCH_DEFAULT_LIMIT=20
RELATA_SEARCH_MAX_RESULTS=100
# Relationship strength below which a link will not pull an item into results.
RELATA_SEARCH_EXPANSION_MIN_SCORE=0.45
RELATA_SEARCH_MAX_EXPANDED_ITEMS=20
RELATA_ANSWER_ENABLED=true
# Passages given to the model per answer. Each one costs model time; six
# completes comfortably with llama3.1:8b on CPU, twelve does not.
RELATA_ANSWER_MAX_CHUNKS=6
RELATA_ANSWER_MAX_CHARS_PER_CHUNK=1200

# --- Relationship discovery and scoring ------------------------------------

# Candidates considered per newly-ingested item. Discovery never compares an
# item with every other item.
RELATA_REL_MAX_CANDIDATES=40
# Below this strength a candidate is discarded entirely.
RELATA_REL_MIN_SCORE=0.18
# At or above this strength a candidate is stored, pending human review.
# Nothing is ever auto-confirmed.
RELATA_REL_STORE_SCORE=0.25
# Language-model classification calls per discovery run.
RELATA_REL_MAX_MODEL_CALLS=8
# Cosine similarity at which two items are flagged as likely near-duplicates.
# They are flagged, never merged.
RELATA_NEAR_DUPLICATE_SIMILARITY=0.94
RELATA_REL_TEMPORAL_WINDOW=168h
RELATA_REL_MAX_NEIGHBOURS_PER_CHUNK=10

# --- Sessions and authentication -------------------------------------------

RELATA_SESSION_COOKIE=relata_session
RELATA_SESSION_IDLE_TIMEOUT=12h
RELATA_SESSION_ABSOLUTE_TIMEOUT=168h
RELATA_LOGIN_RATE_BURST=8
RELATA_LOGIN_RATE_WINDOW=5m

# --- Federated sign-in (OAuth 2.0 / OpenID Connect) -------------------------
#
# The redirect URI to register with your provider is derived from RELATA_BASE_URL
# and a fixed path:
#
#     <RELATA_BASE_URL>/auth/oauth/callback
#
# The path is not configurable, so what you register and what Relata serves
# cannot drift apart.

RELATA_OAUTH_ENABLED=false
RELATA_OAUTH_PROVIDER_NAME=Blackwall

# Supply EITHER an issuer (OIDC discovery fills in the rest, and enables ID
# token signature validation) OR the endpoints directly.
RELATA_OAUTH_ISSUER=
RELATA_OAUTH_AUTHORIZE_URL=
RELATA_OAUTH_TOKEN_URL=
RELATA_OAUTH_USERINFO_URL=
RELATA_OAUTH_JWKS_URL=

# NEVER commit real values. This file is an example; .env is gitignored.
RELATA_OAUTH_CLIENT_ID=
RELATA_OAUTH_CLIENT_SECRET=

RELATA_OAUTH_SCOPES=openid profile email

# Optional allowlist. Empty means any identity the provider vouches for is
# accepted. Subdomains are NOT matched: "example.com" does not admit
# "sub.example.com".
RELATA_OAUTH_ALLOWED_EMAIL_DOMAINS=

RELATA_OAUTH_TIMEOUT=15s

# --- Local (break-glass) sign-in -------------------------------------------
#
# Unset, this defaults to the opposite of RELATA_OAUTH_ENABLED: on while there
# is no identity provider, off once there is one. Set it explicitly to keep a
# password login available alongside OAuth — useful for recovering from a
# broken provider configuration, since `relata createadmin` still works.
#
# A federated account has no password hash and can never sign in locally,
# whatever is submitted.
#RELATA_LOCAL_LOGIN_ENABLED=true

# --- API tokens ------------------------------------------------------------
#
# Bearer credentials people create for themselves in Settings -> API tokens.
# Only a SHA-256 hash is stored, so these bounds are the whole of the lifetime
# control: a token cannot be looked up, extended or re-shown.

RELATA_API_TOKEN_DEFAULT_TTL=2160h   # 90 days
RELATA_API_TOKEN_MAX_TTL=8760h       # 365 days

# --- Administrator creation ------------------------------------------------

# Only for unattended setup. Prefer the interactive prompt, which does not
# place the password in the environment or in shell history.
# RELATA_ADMIN_PASSWORD=