Environment

R2R Troubleshooting Guide: Missing Environment Variables

When deploying R2R, missing environment variables can cause containers to fail to start or lead to unexpected behavior. This guide will help you identify and resolve issues related to missing environment variables.

1. Identifying the Problem

Signs that you might be dealing with missing environment variables:

  • Containers exit immediately after starting
  • Error messages in logs mentioning undefined or null values
  • Specific features or integrations not working as expected

2. Common Missing Environment Variables

Here are some critical environment variables for R2R:

  • Database credentials (e.g., R2R_POSTGRES_USER, R2R_POSTGRES_PASSWORD)
  • API keys (e.g., OPENAI_API_KEY, ANTHROPIC_API_KEY)
  • Configuration settings (e.g., R2R_CONFIG_NAME, R2R_CONFIG_PATH)

3. Checking for Missing Variables

3.1 Review Docker Compose File

  1. Open your docker-compose.yml file.
  2. Look for the environment section under the r2r service.
  3. Ensure all required variables are listed.

Example:

1services:
2  r2r:
3    environment:
4      - R2R_POSTGRES_USER=${R2R_POSTGRES_USER:-postgres}
5      - OPENAI_API_KEY=${OPENAI_API_KEY:-}
6      - R2R_CONFIG_NAME=${R2R_CONFIG_NAME:-}
7      # ... other variables

3.2 Check .env File

  1. Ensure you have a .env file in the same directory as your docker-compose.yml.
  2. Verify that all variables used in docker-compose.yml are defined in .env.

Example .env file:

R2R_POSTGRES_USER=myuser
OPENAI_API_KEY=sk-...
R2R_CONFIG_NAME=default

3.3 Verify Environment in Running Container

If the container starts but behaves unexpectedly:

  1. Access the container’s shell: 
    docker exec -it r2r-container-name /bin/bash
  2. Check environment variables: 
    env | grep VARIABLE_NAME

4. Resolving Missing Variables

4.1 Update .env File

  1. Add any missing variables to your .env file.
  2. Ensure values are correct and properly formatted.

4.2 Use Default Values

In docker-compose.yml, provide default values for non-sensitive variables:

1environment:
2  - VARIABLE_NAME=${VARIABLE_NAME:-default_value}

4.3 Inject Variables at Runtime

For sensitive data, inject variables when running the container:

$docker run -e SENSITIVE_VAR=value ...

Or with docker-compose:

$SENSITIVE_VAR=value docker-compose up

4.4 Use Docker Secrets

For enhanced security, consider using Docker secrets for sensitive data:

  1. Create a secret:

    echo "mysecretvalue" | docker secret create my_secret -

  2. Use in docker-compose.yml:

    1secrets:
    2  - my_secret

5. Specific R2R Environment Variables

Ensure these key R2R variables are set:

  • R2R_CONFIG_NAME or R2R_CONFIG_PATH: Specifies which configuration to use.
  • R2R_POSTGRES_*: Database connection details.
  • OPENAI_API_KEY: If using OpenAI services.
  • ANTHROPIC_API_KEY: If using Anthropic models.
  • OLLAMA_API_BASE: For local LLM integration.
  • HATCHET_CLIENT_TOKEN: For Hatchet integration.

6. Debugging Tips

  • Use docker-compose config to see the final composed configuration with resolved variables.
  • Temporarily echo sensitive variables in your container’s entrypoint script for debugging (remove in production).
  • Check for typos in variable names both in docker-compose.yml and .env files.

7. Best Practices

  • Use version control for your docker-compose.yml, but not for .env files containing secrets.
  • Consider using a secret management service for production deployments.
  • Document all required environment variables in your project’s README.
  • Use CI/CD pipelines to validate the presence of required variables before deployment.

By following this guide, you should be able to identify and resolve issues related to missing environment variables in your R2R deployment. Remember to always handle sensitive data securely and never commit secrets to version control.