Deployment
/
Configuration Reference
Last updated

Configuration Reference

Complete reference for all environment variables and configuration options for self-hosted Papr Memory.

Environment File Setup

Create a .env file in your project root:

# Copy from example
cp .env.example .env.opensource

# Edit with your values
nano .env.opensource

Core Configuration

Server Settings

# Server port (default: 5001)
PORT=5001

# Debug mode - set to false in production
DEBUG=false

# Environment: development, staging, production
ENVIRONMENT=production

# Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL
LOG_LEVEL=INFO

# API server host binding
HOST=0.0.0.0

Database Connections

MongoDB

# MongoDB connection string
MONGODB_URL=mongodb://localhost:27017/papr_memory

# With authentication
MONGODB_URL=mongodb://username:password@localhost:27017/papr_memory?authSource=admin

# MongoDB replica set
MONGODB_URL=mongodb://host1:27017,host2:27017,host3:27017/papr_memory?replicaSet=rs0

# Database name (default: papr_memory)
MONGODB_DATABASE=papr_memory

Options:

  • authSource=admin - Authentication database
  • replicaSet=rs0 - Replica set name
  • ssl=true - Enable SSL/TLS
  • retryWrites=true - Automatic retry for writes

Neo4j

# Neo4j connection URL (Bolt protocol)
NEO4J_URL=bolt://localhost:7687

# Neo4j username (default: neo4j)
NEO4J_USER=neo4j

# Neo4j password (CHANGE IN PRODUCTION!)
NEO4J_PASSWORD=your-secure-password

# Neo4j database (default: neo4j)
NEO4J_DATABASE=neo4j

# Connection timeout (seconds)
NEO4J_TIMEOUT=30

# Max connection pool size
NEO4J_MAX_POOL_SIZE=50

Security Note: Always change the default Neo4j password!

Qdrant

# Qdrant HTTP URL
QDRANT_URL=http://localhost:6333

# Qdrant API key (if enabled)
QDRANT_API_KEY=your-qdrant-api-key

# Collection name for memories
QDRANT_COLLECTION=papr_memories

# Vector dimension (default: 1536 for OpenAI)
QDRANT_VECTOR_SIZE=1536

# Distance metric: Cosine, Euclidean, Dot
QDRANT_DISTANCE_METRIC=Cosine

Redis

# Redis URL
REDIS_URL=redis://localhost:6379

# With password
REDIS_URL=redis://:password@localhost:6379

# Redis database number (0-15)
REDIS_DB=0

# Connection timeout (seconds)
REDIS_TIMEOUT=5

# Max connections
REDIS_MAX_CONNECTIONS=50

# TTL for cached items (seconds, default: 3600 = 1 hour)
REDIS_CACHE_TTL=3600

Parse Server

# Parse Server URL
PARSE_SERVER_URL=http://localhost:1337/parse

# Parse application ID (CHANGE IN PRODUCTION!)
PARSE_SERVER_APP_ID=your-unique-app-id

# Parse master key (CHANGE IN PRODUCTION!)
PARSE_SERVER_MASTER_KEY=your-secure-master-key

# Parse JavaScript key (optional)
PARSE_SERVER_JAVASCRIPT_KEY=your-javascript-key

# Parse REST API key (optional)
PARSE_SERVER_REST_API_KEY=your-rest-api-key

Security Note: Generate secure random keys for production:

# Generate secure keys
openssl rand -hex 32  # For PARSE_SERVER_APP_ID
openssl rand -hex 64  # For PARSE_SERVER_MASTER_KEY

AI Service Configuration

OpenAI

# OpenAI API key (required)
OPENAI_API_KEY=sk-your-openai-api-key-here

# OpenAI organization (optional)
OPENAI_ORGANIZATION=org-your-organization-id

# Model for embeddings (default: text-embedding-3-small)
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

# Model for chat/completions (default: gpt-4-turbo-preview)
OPENAI_CHAT_MODEL=gpt-4-turbo-preview

# Max retries for API calls
OPENAI_MAX_RETRIES=3

# Request timeout (seconds)
OPENAI_TIMEOUT=60

Available Embedding Models:

  • text-embedding-3-small - Faster, lower cost (1536 dimensions)
  • text-embedding-3-large - Higher accuracy (3072 dimensions)
  • text-embedding-ada-002 - Legacy model (1536 dimensions)

Groq

# Groq API key (required)
GROQ_API_KEY=gsk-your-groq-api-key-here

# Model for fast inference (default: mixtral-8x7b-32768)
GROQ_MODEL=mixtral-8x7b-32768

# Max retries
GROQ_MAX_RETRIES=3

# Request timeout (seconds)
GROQ_TIMEOUT=30

Available Groq Models:

  • mixtral-8x7b-32768 - Balanced performance
  • llama2-70b-4096 - High accuracy
  • gemma-7b-it - Fast and efficient

Deep Infra

# Deep Infra API key (required)
DEEPINFRA_API_KEY=your-deepinfra-api-key-here

# Model selection
DEEPINFRA_MODEL=meta-llama/Llama-2-70b-chat-hf

# Max retries
DEEPINFRA_MAX_RETRIES=3

# Request timeout (seconds)
DEEPINFRA_TIMEOUT=60

Hugging Face (Optional)

# Hugging Face API key (optional)
HUGGINGFACE_API_KEY=hf-your-huggingface-token

# Model for embeddings
HUGGINGFACE_EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2

# Inference endpoint (optional)
HUGGINGFACE_ENDPOINT=https://api-inference.huggingface.co

Feature Flags

# Enable/disable features

# Enable graph generation (default: true)
ENABLE_GRAPH_GENERATION=true

# Enable predictive caching (default: true)
ENABLE_PREDICTIVE_CACHING=true

# Enable document processing (default: true)
ENABLE_DOCUMENT_PROCESSING=true

# Enable GraphQL queries (default: true)
ENABLE_GRAPHQL=true

# Enable custom schemas (default: true)
ENABLE_CUSTOM_SCHEMAS=true

# Enable search feedback (default: true)
ENABLE_SEARCH_FEEDBACK=true

Performance Tuning

Memory & Processing

# Max memories per search (default: 20)
MAX_MEMORIES_PER_SEARCH=20

# Max graph nodes per search (default: 15)
MAX_GRAPH_NODES_PER_SEARCH=15

# Chunk size for document processing (default: 1000)
DOCUMENT_CHUNK_SIZE=1000

# Chunk overlap (default: 200)
DOCUMENT_CHUNK_OVERLAP=200

# Max workers for parallel processing (default: 4)
MAX_WORKERS=4

Caching

# Enable Redis caching (default: true)
ENABLE_REDIS_CACHE=true

# Cache TTL for memories (seconds, default: 3600)
MEMORY_CACHE_TTL=3600

# Cache TTL for search results (seconds, default: 1800)
SEARCH_CACHE_TTL=1800

# Cache TTL for embeddings (seconds, default: 86400 = 24 hours)
EMBEDDING_CACHE_TTL=86400

Rate Limiting

# Enable rate limiting (default: true)
ENABLE_RATE_LIMITING=true

# Requests per minute per API key (default: 60)
RATE_LIMIT_PER_MINUTE=60

# Requests per hour per API key (default: 1000)
RATE_LIMIT_PER_HOUR=1000

# Burst allowance (default: 10)
RATE_LIMIT_BURST=10

Security Configuration

API Security

# Require API key for all requests (default: true)
REQUIRE_API_KEY=true

# API key prefix (default: mem_)
API_KEY_PREFIX=mem_

# API key expiration (days, 0 = never, default: 0)
API_KEY_EXPIRATION_DAYS=0

# Allow anonymous reads (default: false)
ALLOW_ANONYMOUS_READS=false

CORS Settings

# CORS enabled (default: true)
CORS_ENABLED=true

# Allowed origins (comma-separated)
CORS_ORIGINS=http://localhost:3000,https://yourdomain.com

# Allow credentials (default: true)
CORS_ALLOW_CREDENTIALS=true

# Allowed methods
CORS_METHODS=GET,POST,PUT,DELETE,OPTIONS

# Allowed headers
CORS_HEADERS=Content-Type,Authorization,X-API-Key

SSL/TLS

# SSL certificate path (for HTTPS)
SSL_CERT_PATH=/path/to/cert.pem

# SSL key path
SSL_KEY_PATH=/path/to/key.pem

# Redirect HTTP to HTTPS (default: false)
FORCE_HTTPS=false

Monitoring & Observability

Logging

# Log format: json, text (default: json)
LOG_FORMAT=json

# Log output: stdout, file (default: stdout)
LOG_OUTPUT=stdout

# Log file path (if LOG_OUTPUT=file)
LOG_FILE_PATH=/var/log/papr/memory.log

# Log rotation max size (MB)
LOG_MAX_SIZE=100

# Log rotation max files
LOG_MAX_FILES=10

Metrics

# Enable Prometheus metrics (default: false)
ENABLE_METRICS=false

# Metrics endpoint path (default: /metrics)
METRICS_PATH=/metrics

# Metrics port (default: 9090)
METRICS_PORT=9090

Tracing

# Enable distributed tracing (default: false)
ENABLE_TRACING=false

# Jaeger agent host
JAEGER_AGENT_HOST=localhost

# Jaeger agent port
JAEGER_AGENT_PORT=6831

# Service name for tracing
TRACING_SERVICE_NAME=papr-memory

Docker-Specific Configuration

When running in Docker, these environment variables are typically set in docker-compose.yml:

environment:
  # Use service names for inter-container communication
  - MONGODB_URL=mongodb://mongodb:27017/papr_memory
  - NEO4J_URL=bolt://neo4j:7687
  - QDRANT_URL=http://qdrant:6333
  - REDIS_URL=redis://redis:6379
  - PARSE_SERVER_URL=http://parse-server:1337/parse

Production Checklist

Before deploying to production, ensure:

Security

  • Changed all default passwords (Neo4j, Parse, Redis)
  • Generated secure random keys for Parse Server
  • Enabled SSL/TLS for all connections
  • Configured firewall rules
  • Set DEBUG=false
  • Configured CORS properly
  • Enabled rate limiting

Performance

  • Configured appropriate resource limits
  • Enabled Redis caching
  • Set up database indexes
  • Configured connection pooling
  • Tuned chunk sizes for your use case

Reliability

  • Configured health checks
  • Set up monitoring and alerts
  • Configured backups
  • Tested disaster recovery
  • Set ENVIRONMENT=production

Observability

  • Configured structured logging
  • Set up metrics collection
  • Enabled distributed tracing (optional)
  • Configured log aggregation

Example Configurations

Development

# .env.development
PORT=5001
DEBUG=true
ENVIRONMENT=development
LOG_LEVEL=DEBUG

MONGODB_URL=mongodb://localhost:27017/papr_memory_dev
NEO4J_URL=bolt://localhost:7687
NEO4J_PASSWORD=password
QDRANT_URL=http://localhost:6333
REDIS_URL=redis://localhost:6379

OPENAI_API_KEY=sk-dev-key
GROQ_API_KEY=gsk-dev-key
DEEPINFRA_API_KEY=dev-key

ENABLE_RATE_LIMITING=false
CORS_ORIGINS=http://localhost:3000,http://localhost:3001

Staging

# .env.staging
PORT=5001
DEBUG=false
ENVIRONMENT=staging
LOG_LEVEL=INFO

MONGODB_URL=mongodb://user:pass@mongodb-staging:27017/papr_memory?authSource=admin
NEO4J_URL=bolt://neo4j-staging:7687
NEO4J_PASSWORD=staging-secure-password
QDRANT_URL=http://qdrant-staging:6333
REDIS_URL=redis://:staging-redis-pass@redis-staging:6379

OPENAI_API_KEY=sk-staging-key
GROQ_API_KEY=gsk-staging-key
DEEPINFRA_API_KEY=staging-key

ENABLE_RATE_LIMITING=true
RATE_LIMIT_PER_MINUTE=100
CORS_ORIGINS=https://staging.yourdomain.com

Production

# .env.production
PORT=5001
DEBUG=false
ENVIRONMENT=production
LOG_LEVEL=WARNING
LOG_FORMAT=json

MONGODB_URL=mongodb://prod-user:secure-pass@mongodb-prod:27017/papr_memory?authSource=admin&ssl=true
NEO4J_URL=bolt://neo4j-prod:7687
NEO4J_PASSWORD=production-very-secure-password
QDRANT_URL=http://qdrant-prod:6333
QDRANT_API_KEY=production-qdrant-key
REDIS_URL=redis://:production-redis-pass@redis-prod:6379

OPENAI_API_KEY=sk-production-key
GROQ_API_KEY=gsk-production-key
DEEPINFRA_API_KEY=production-key

ENABLE_RATE_LIMITING=true
RATE_LIMIT_PER_MINUTE=60
RATE_LIMIT_PER_HOUR=1000

CORS_ORIGINS=https://yourdomain.com,https://app.yourdomain.com
FORCE_HTTPS=true

ENABLE_METRICS=true
ENABLE_TRACING=true

Environment Variable Priority

Configuration is loaded in this order (later overrides earlier):

  1. Default values in code
  2. .env file
  3. Environment variables
  4. Command line arguments (if applicable)

Validation

The application validates all required environment variables on startup. If any are missing or invalid, you'll see clear error messages:

❌ Configuration Error: OPENAI_API_KEY is required but not set
❌ Configuration Error: NEO4J_PASSWORD cannot be the default 'password' in production
✅ Configuration validated successfully

Next Steps

🚀 Self-Hosted Setup

Complete deployment guide

🐳 Docker Configuration

Docker Compose details

📚 Feature Guides

Learn about all features

Previous page
Next page