Configuration

The complete non-embeddings environment reference for the RAG API — server, authentication, vector database (pgvector and MongoDB Atlas), chunking, batching, document processing, logging, and proxy settings.

The RAG API is configured entirely through environment variables, set in config/.env under the same names the container reads (documented below). This page covers everything except the embeddings-provider settings, which have their own Embeddings providers page.

Server

Name	Purpose	Default	Required
`RAG_HOST`	Bind address for the FastAPI server	`0.0.0.0`	No
`RAG_PORT`	Port for the FastAPI server	`8000`	No
`RAG_UPLOAD_DIR`	Directory for uploaded files awaiting processing	`./uploads/`	No
`RAG_THREAD_POOL_SIZE`	Worker threads for CPU-bound sync work (parsing, embeddings)	`min(cpu_count, 8)`	No

The server exposes GET /health, GET /docs, and GET /openapi.json without authentication; all other routes require a JWT when JWT_SECRET is set.

Authentication

Name	Purpose	Default	Required
`JWT_SECRET`	Secret used to verify HS256 bearer tokens	(unset)	No

Set JWT_SECRET in production

If JWT_SECRET is unset, the API runs without authentication — any client that can reach it can index or query documents. In the stack, set it to the same secret the IntelliAsk app uses to sign RAG requests. All routes except /health, /docs, and /openapi.json then require an Authorization: Bearer <token> header.

Vector database

The RAG API supports two vector backends, selected by VECTOR_DB_TYPE.

Name	Purpose	Default	Required
`VECTOR_DB_TYPE`	Backend: `pgvector` or `atlas-mongo`	`pgvector`	No

PostgreSQL + pgvector (default)

Name	Purpose	Default	Required
`DB_HOST`	PostgreSQL host (or socket path if using Unix sockets)	`db`	No
`DB_PORT`	PostgreSQL port	`5432`	No
`POSTGRES_DB`	Database name (must have the pgvector extension)	`mydatabase`	No
`POSTGRES_USER`	Database user (needs `CREATE TABLE`/`CREATE INDEX`)	`myuser`	No
`POSTGRES_PASSWORD`	Database password	`mypassword`	No
`POSTGRES_USE_UNIX_SOCKET`	Connect via Unix socket instead of TCP	`false`	No
`COLLECTION_NAME`	pgvector collection/table name for embeddings	`testcollection`	No

Connection string forms:

TCP: postgresql+psycopg2://user:pass@host:port/dbname
Unix socket (POSTGRES_USE_UNIX_SOCKET=true): postgresql+psycopg2://user:pass@/dbname?host=/socket/path

Requires the pgvector extension (≥ 0.5.0). In the stack this is provided by the bundled Vector DB component, which shares the same DB_*/POSTGRES_* keys above.

MongoDB Atlas (alternative)

Used only when VECTOR_DB_TYPE=atlas-mongo.

Name	Purpose	Default	Required
`ATLAS_MONGO_DB_URI`	MongoDB Atlas connection string (SRV URI)	`mongodb://127.0.0.1:27018/IntelliAsk`	No
`COLLECTION_NAME`	Collection name for embeddings	`testcollection`	No
`ATLAS_SEARCH_INDEX`	Atlas vector search index name (must exist)	`vector_index`	No
`MONGO_VECTOR_COLLECTION`	Deprecated — legacy override for collection + index	(unset)	No

An Atlas vector search index must be created on the collection before indexing, for example:

{
  "fields": [
    { "type": "vector", "path": "embedding", "numDimensions": 1536, "similarity": "cosine" },
    { "type": "filter", "path": "file_id" }
  ]
}

Chunking & retrieval

Name	Purpose	Default	Required
`CHUNK_SIZE`	Chunk size in tokens for text splitting	`1500`	No
`CHUNK_OVERLAP`	Overlapping tokens between adjacent chunks	`100`	No

Larger chunks preserve more context per vector but use more memory; overlap is typically 10–20% of CHUNK_SIZE to avoid losing context at boundaries.

Batching (memory tuning)

Embedding runs in memory-bounded batches. Peak memory ≈ EMBEDDING_BATCH_SIZE × EMBEDDING_MAX_QUEUE_SIZE.

Name	Purpose	Default	Required
`EMBEDDING_BATCH_SIZE`	Chunks embedded per batch (`0` disables batching)	`500`	No
`EMBEDDING_MAX_QUEUE_SIZE`	Max batches buffered in memory during async processing	`3`	No

Profile	Suggested settings
Memory-constrained (< 2 GB)	`EMBEDDING_BATCH_SIZE=100`, `EMBEDDING_MAX_QUEUE_SIZE=2`
Default	`EMBEDDING_BATCH_SIZE=500`, `EMBEDDING_MAX_QUEUE_SIZE=3`
High-throughput	`EMBEDDING_BATCH_SIZE=750`, `EMBEDDING_MAX_QUEUE_SIZE=5`

Document processing

Name	Purpose	Default	Required
`PDF_EXTRACT_IMAGES`	Extract and process images embedded in PDFs	`false`	No

Logging & debugging

Name	Purpose	Default	Required
`DEBUG_RAG_API`	Verbose debug logging (also enables `/db/*` debug routes)	`false`	No
`DEBUG_PGVECTOR_QUERIES`	Log every pgvector SQL query with timing	`false`	No
`CONSOLE_JSON`	Emit structured JSON logs (for log aggregation)	`false`	No

DEBUG_PGVECTOR_QUERIES has a significant performance cost and DEBUG_RAG_API exposes debug database routes — keep both false in production.

Proxy (corporate networks)

Name	Purpose	Default	Required
`HTTP_PROXY`	HTTP proxy for all outbound requests from the container	(unset)	No
`HTTPS_PROXY`	HTTPS proxy for all outbound requests	(unset)	No

These apply to every external call (OpenAI, HuggingFace, Google, AWS, …) — useful in air-gapped or proxied environments.

Applying changes

The RAG API reads env at startup, so after editing any RAG_* value recreate the service:

intelliask up rag-api

RAG is disabled by default

RAG is an optional module the stack ships disabled (it needs an embeddings provider first). If rag-api isn't running, enable the module instead — this clears it from DISABLED_MODULES and starts it:

intelliask module enable rag

Disable it again with intelliask module disable rag.

Run intelliask env doctor first to confirm the variables are wired between config/.env and the compose files.