Environment variables

The RAG Support System requires several environment variables for external service integration. This guide covers all configuration options.

Required variables

These environment variables are required for the system to function. The application will fail to start if they are missing.

OPENAI_API_KEY

Purpose: Authentication for OpenAI API (embeddings and LLM) Used by:

OpenAIEmbeddings for document and query embeddings
ChatOpenAI for answer generation

How to obtain:

Create an account at platform.openai.com
Navigate to API keys section
Create a new secret key
Copy the key (it will only be shown once)

Example:

OPENAI_API_KEY=sk-proj-abc123def456...

The system uses text-embedding-3-small for embeddings and gpt-4.1 for generation. Ensure your API key has access to these models.

UNSTRUCTURED_API_KEY

Purpose: Authentication for Unstructured.io API (document parsing) Used by:

Document ingestion pipeline (src/rag/ingest.py)
Markdown file parsing and chunking

How to obtain:

Sign up at unstructured.io
Navigate to API settings
Generate an API key

Example:

UNSTRUCTURED_API_KEY=your_unstructured_api_key

The Unstructured API is only needed for document ingestion. If you’re only querying the RAG system (not adding new documents), this key is optional.

Configuration file

Create a .env file in the project root:

.env

# OpenAI Configuration
OPENAI_API_KEY=sk-proj-abc123def456...

# Unstructured.io Configuration
UNSTRUCTURED_API_KEY=your_unstructured_api_key

Security best practices:

Never commit .env to version control (already in .gitignore)
Use different API keys for development and production
Rotate keys regularly
Set up billing alerts in OpenAI dashboard
Use read-only keys where possible

Loading environment variables

The system automatically loads variables from .env using python-dotenv:

src/config.py

import os
from dotenv import load_dotenv

load_dotenv()

OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
UNSTRUCTURED_API_KEY = os.getenv("UNSTRUCTURED_API_KEY")

Setting variables by environment

Development (local)
Docker
Production
CI/CD

Create a .env file in the project root:

# .env
OPENAI_API_KEY=sk-proj-...
UNSTRUCTURED_API_KEY=...

The application will automatically load these values.

When using Docker Compose, the .env file is automatically loaded:

docker-compose.yml

services:
  app:
    env_file:
      - .env

Alternatively, set variables directly:

services:
  app:
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - UNSTRUCTURED_API_KEY=${UNSTRUCTURED_API_KEY}

Recommended: Use secrets management instead of .env filesCloud platforms:

AWS: Use AWS Secrets Manager or Parameter Store
GCP: Use Secret Manager
Azure: Use Key Vault
Kubernetes: Use Secrets

Example with Kubernetes:

apiVersion: v1
kind: Secret
metadata:
  name: rag-api-secrets
type: Opaque
stringData:
  OPENAI_API_KEY: sk-proj-...
  UNSTRUCTURED_API_KEY: ...

Reference in deployment:

env:
  - name: OPENAI_API_KEY
    valueFrom:
      secretKeyRef:
        name: rag-api-secrets
        key: OPENAI_API_KEY

Set as repository secrets in your CI/CD platform:GitHub Actions:

env:
  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
  UNSTRUCTURED_API_KEY: ${{ secrets.UNSTRUCTURED_API_KEY }}

Note: For testing, use mock values or test-specific keys with rate limits.

Optional configuration

While not currently configurable via environment variables, these settings can be modified in the source code:

LLM configuration

Located in src/rag/retriever.py:

DEFAULT_EMBEDDING_MODEL = "text-embedding-3-small"
DEFAULT_LLM_MODEL = "gpt-4.1"
DEFAULT_TEMPERATURE = 0.0

CATEGORY_CONF_THRESHOLD = 0.5
PRIORITY_CONF_THRESHOLD = 0.5

Vector store configuration

Located in SimpleRetrievalAgent.__init__:

collection_name: str = "docs_collection"
persist_dir: str = "./chroma_db"

API server configuration

Located in main.py:

if __name__ == "__main__":
    uvicorn.run(
        "main:app",
        host="0.0.0.0",
        port=8000,
        log_level="info",
    )

Future enhancement: These could be made configurable via environment variables for easier deployment customization.

Verification

Verify your environment variables are loaded correctly:

import os
from dotenv import load_dotenv

load_dotenv()

# Check if keys are present (don't print the actual values!)
print(f"OPENAI_API_KEY is set: {bool(os.getenv('OPENAI_API_KEY'))}")
print(f"UNSTRUCTURED_API_KEY is set: {bool(os.getenv('UNSTRUCTURED_API_KEY'))}")

Or test API connectivity:

# Start the server
uv run main.py

# In another terminal, test the health endpoint
curl http://localhost:8000/api/v1/health

Troubleshooting

KeyError: 'OPENAI_API_KEY'

Cause: Environment variable not set or .env file not foundSolutions:

Check .env file exists in project root
Verify variable name spelling (case-sensitive)
Ensure python-dotenv is installed: uv sync
Try loading manually: export OPENAI_API_KEY=your_key

OpenAI AuthenticationError

Error: openai.AuthenticationError: Invalid API keyCauses:

Invalid or expired API key
Whitespace in the key value
Key not activated in OpenAI dashboard

Solution:

Regenerate API key in OpenAI dashboard
Copy key without extra spaces
Update .env file
Restart the application

Rate limit errors

Error: RateLimitError: Rate limit exceededCause: Too many API requests in a short periodSolutions:

Check OpenAI dashboard for current limits
Upgrade to a paid tier for higher limits
Implement request throttling
Use caching for repeated queries

Environment variables not loading in Docker

Cause: .env file not mounted or env_file not configuredSolution:

docker-compose.yml

services:
  app:
    env_file:
      - .env  # Ensure this line exists

Verify:

docker exec -it rag_api printenv | grep OPENAI

Security checklist

Protect your .env file

# Verify .env is in .gitignore
grep .env .gitignore

# Set restrictive permissions
chmod 600 .env

Use separate keys per environment

Development: Test API key with rate limits
Staging: Separate key for integration testing
Production: Dedicated key with monitoring

Enable billing alerts

Set up alerts in the OpenAI dashboard to prevent unexpected charges.

Rotate keys regularly

Generate new keys every 90 days
Update all deployment environments
Revoke old keys immediately

Monitor usage

Track API costs in OpenAI dashboard
Set up logging for API calls
Review access patterns regularly

Next steps

Docker deployment

Deploy using Docker and Docker Compose

Production deployment

Production best practices and scaling

Installation

Complete installation guide

Quickstart

Get started in 5 minutes

Getting Started

Core Concepts

Guides

Deployment

Required variables

OPENAI_API_KEY

UNSTRUCTURED_API_KEY

Configuration file

Loading environment variables

Setting variables by environment

Optional configuration

LLM configuration

Vector store configuration

API server configuration

Verification

Troubleshooting

Security checklist

Next steps

Docker deployment

Production deployment

Installation

Quickstart

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Guides

Deployment

​Required variables

​OPENAI_API_KEY

​UNSTRUCTURED_API_KEY

​Configuration file

​Loading environment variables

​Setting variables by environment

​Optional configuration

​LLM configuration

​Vector store configuration

​API server configuration

​Verification

​Troubleshooting

​Security checklist

​Next steps

Docker deployment

Production deployment

Installation

Quickstart

Build docs developers (and LLMs) love

Required variables

OPENAI_API_KEY

UNSTRUCTURED_API_KEY

Configuration file

Loading environment variables

Setting variables by environment

Optional configuration

LLM configuration

Vector store configuration

API server configuration

Verification

Troubleshooting

Security checklist

Next steps