Skip to main content

Environment variables reference

Complete list of environment variables for configuring Chive.

Required variables​

These must be set for Chive to start:

VariableDescriptionExample
POSTGRES_PASSWORDPostgreSQL passwordsecretpassword
NEO4J_PASSWORDNeo4j passwordsecretpassword
JWT_SECRETJWT signing secret (min 32 chars)your-256-bit-secret
FIREHOSE_URLATProto relay WebSocket URLwss://bsky.network

Server​

VariableDefaultDescription
NODE_ENVdevelopmentEnvironment (development/production/test)
PORT3000HTTP server port
HOST0.0.0.0Bind address
TRUST_PROXYfalseTrust X-Forwarded-* headers
CORS_ORIGINS*Allowed CORS origins (comma-separated)
REQUEST_TIMEOUT30000Request timeout in milliseconds
BODY_LIMIT10mbMaximum request body size

PostgreSQL​

VariableDefaultDescription
POSTGRES_HOSTlocalhostDatabase host
POSTGRES_PORT5432Database port
POSTGRES_DBchiveDatabase name
POSTGRES_USERchiveUsername
POSTGRES_PASSWORDRequiredPassword
POSTGRES_POOL_MIN5Minimum pool connections
POSTGRES_POOL_MAX20Maximum pool connections
POSTGRES_SSLfalseEnable SSL connection
DATABASE_URLNoneFull connection string (overrides individual vars)

Elasticsearch​

VariableDefaultDescription
ELASTICSEARCH_URLhttp://localhost:9200Cluster URL
ELASTICSEARCH_USERNoneUsername for auth
ELASTICSEARCH_PASSWORDNonePassword for auth
ELASTICSEARCH_INDEX_PREFIXchivePrefix for index names
ELASTICSEARCH_SHARDS3Shards per index
ELASTICSEARCH_REPLICAS2Replicas per shard

Neo4j​

VariableDefaultDescription
NEO4J_URIbolt://localhost:7687Bolt connection URI
NEO4J_USERneo4jUsername
NEO4J_PASSWORDRequiredPassword
NEO4J_DATABASEneo4jDatabase name
NEO4J_MAX_POOL_SIZE50Connection pool size

Redis​

VariableDefaultDescription
REDIS_HOSTlocalhostRedis host
REDIS_PORT6379Redis port
REDIS_PASSWORDNonePassword
REDIS_DB0Database number (0-15)
REDIS_TLSfalseEnable TLS
REDIS_URLNoneFull connection string (overrides individual vars)

Authentication​

VariableDefaultDescription
JWT_SECRETRequiredSecret for signing JWTs
JWT_EXPIRY7dToken expiration time
SESSION_TTL604800Session TTL in seconds (7 days)
MFA_REQUIREDfalseRequire multi-factor auth
OAUTH_CLIENT_IDNoneOAuth client ID for ATProto
OAUTH_CLIENT_SECRETNoneOAuth client secret

Rate limiting​

VariableDefaultDescription
RATE_LIMIT_ENABLEDtrueEnable rate limiting
RATE_LIMIT_WINDOW60000Window size in milliseconds
RATE_LIMIT_ANONYMOUS30Requests per window (anonymous)
RATE_LIMIT_AUTHENTICATED100Requests per window (authenticated)
RATE_LIMIT_TRUSTED500Requests per window (trusted)
RATE_LIMIT_SERVICE1000Requests per window (service)
DISABLE_RATE_LIMITINGfalseDisable for E2E tests

Firehose​

VariableDefaultDescription
FIREHOSE_URLRequiredRelay WebSocket URL
FIREHOSE_COLLECTIONSpub.chive.*Collections to subscribe to
FIREHOSE_RECONNECT_DELAY5000Reconnect delay in ms
FIREHOSE_MAX_RETRIES10Maximum reconnection attempts
FIREHOSE_CURSORNoneStart from specific cursor

Caching​

VariableDefaultDescription
CACHE_PREPRINT_TTL300Preprint cache TTL (seconds)
CACHE_SEARCH_TTL300Search result cache TTL
CACHE_USER_TTL600User profile cache TTL
CACHE_BLOB_TTL3600Blob cache TTL
CACHE_FIELD_TTL3600Field taxonomy cache TTL

Logging​

VariableDefaultDescription
LOG_LEVELinfoLog level (debug/info/warn/error)
LOG_FORMATjsonLog format (json/pretty)
LOG_TIMESTAMPtrueInclude timestamps
LOG_CALLERfalseInclude caller info

OpenTelemetry​

VariableDefaultDescription
OTEL_ENABLEDfalseEnable OpenTelemetry
OTEL_EXPORTER_OTLP_ENDPOINTNoneOTLP collector endpoint
OTEL_SERVICE_NAMEchiveService name for traces
OTEL_TRACES_SAMPLERparentbased_traceidratioTrace sampler
OTEL_TRACES_SAMPLER_ARG0.1Sampler ratio (0.0-1.0)

Prometheus​

VariableDefaultDescription
METRICS_ENABLEDtrueEnable Prometheus metrics
METRICS_PORT9090Metrics endpoint port
METRICS_PATH/metricsMetrics endpoint path

External APIs​

Semantic Scholar​

VariableDefaultDescription
S2_API_KEYNoneSemantic Scholar API key
S2_RATE_LIMIT100Requests per 5 minutes
S2_TIMEOUT10000Request timeout (ms)

OpenAlex​

VariableDefaultDescription
OPENALEX_EMAILNoneContact email (for polite pool)
OPENALEX_RATE_LIMIT10Requests per second
OPENALEX_TIMEOUT10000Request timeout (ms)

ORCID​

VariableDefaultDescription
ORCID_CLIENT_IDNoneOAuth client ID
ORCID_CLIENT_SECRETNoneOAuth client secret
ORCID_SANDBOXfalseUse sandbox environment

Wikidata​

VariableDefaultDescription
WIKIDATA_SPARQL_ENDPOINThttps://query.wikidata.org/sparqlSPARQL endpoint
WIKIDATA_USER_AGENTChive/1.0User agent for requests

Feature flags​

VariableDefaultDescription
FEATURE_DISCOVERYtrueEnable recommendations
FEATURE_CLAIMINGtrueEnable authorship claiming
FEATURE_GOVERNANCEtrueEnable governance features
FEATURE_BACKLINKStrueEnable Bluesky backlinks
FEATURE_ENRICHMENTtrueEnable external enrichment

Worker​

VariableDefaultDescription
WORKER_CONCURRENCY5Concurrent jobs per worker
WORKER_QUEUESindexing,enrichmentQueues to process
WORKER_MAX_STALENESS3600000Max job age before stale (ms)

Frontend (Next.js)​

VariableDefaultDescription
NEXT_PUBLIC_API_URL/apiAPI base URL
NEXT_PUBLIC_APP_URLhttps://chive.pubApplication URL
NEXT_PUBLIC_ANALYTICS_IDNoneAnalytics tracking ID

Development​

VariableDefaultDescription
DEBUGNoneDebug namespaces (e.g., chive:*)
SEED_DATAfalseLoad seed data on startup
SKIP_MIGRATIONSfalseSkip database migrations

Example .env file​

# Required
POSTGRES_PASSWORD=your-postgres-password
NEO4J_PASSWORD=your-neo4j-password
JWT_SECRET=your-256-bit-jwt-secret-key-here
FIREHOSE_URL=wss://bsky.network

# Optional overrides
NODE_ENV=production
PORT=3000
LOG_LEVEL=info

# Database connections
POSTGRES_HOST=postgres.example.com
ELASTICSEARCH_URL=https://es.example.com:9200
NEO4J_URI=bolt://neo4j.example.com:7687
REDIS_HOST=redis.example.com

# External APIs
S2_API_KEY=your-semantic-scholar-key
OPENALEX_EMAIL=your-email@example.com
ORCID_CLIENT_ID=APP-XXXXXXXX
ORCID_CLIENT_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# Observability
OTEL_ENABLED=true
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318