Skip to content

ENV_VARS.md

Latest commit

 

History

History
793 lines (607 loc) · 17.8 KB

ENV_VARS.md

File metadata and controls

793 lines (607 loc) · 17.8 KB

Environment Variables Documentation

Version: 1.0 Date: 2025-11-18 Purpose: Complete reference for all environment variables across BlackRoad OS infrastructure

Overview

This document provides the complete list of environment variables used across the BlackRoad OS ecosystem. It covers:

  • Required variables for core functionality
  • Optional variables for integrations and features
  • Where to set them (Railway, GitHub Actions, local development)
  • How to generate secret values safely
  • Security best practices

Table of Contents

  1. Core Application
  2. Database & Cache
  3. Authentication & Security
  4. API Integrations
  5. Infrastructure
  6. Deployment
  7. Observability
  8. Where to Set Variables
  9. Security Best Practices
  10. Quick Start Templates

Core Application

ENVIRONMENT

Required: Yes Default: development Valid values: development, staging, production Description: Runtime environment identifier

Where to set:

  • Railway (production): production
  • Railway (staging): staging
  • Local: development

Example:

ENVIRONMENT=production

DEBUG

Required: No Default: False Valid values: True, False Description: Enable debug mode (verbose logging, stack traces)

⚠️ Security Warning: MUST be False in production!

Where to set:

  • Railway: False
  • Local: True (for development)

Example:

DEBUG=False

SECRET_KEY

Required: Yes Description: Secret key for signing sessions, JWT tokens, and encryption

How to generate:

# Option 1: Using openssl
openssl rand -hex 32

# Option 2: Using Python
python -c "import secrets; print(secrets.token_hex(32))"

⚠️ Security:

  • MUST be unique per environment (production ≠ staging ≠ local)
  • MUST be at least 32 characters
  • NEVER commit to git
  • Rotate quarterly or after suspected compromise

Where to set:

  • Railway (production): Generate unique value
  • Railway (staging): Generate different unique value
  • Local: Generate local value (in .env, gitignored)

Example:

SECRET_KEY=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

API_BASE_URL

Required: Yes Description: Public URL for the backend API (used by frontend for API calls)

Where to set:

  • Railway (production): https://os.blackroad.systems
  • Railway (staging): https://staging.blackroad.systems
  • Local: http://localhost:8000

Example:

API_BASE_URL=https://os.blackroad.systems

FRONTEND_URL

Required: Yes Description: Public URL for the frontend (used for CORS, redirects, emails)

Where to set:

  • Railway (production): https://os.blackroad.systems
  • Railway (staging): https://staging.blackroad.systems
  • Local: http://localhost:8000

Example:

FRONTEND_URL=https://os.blackroad.systems

ALLOWED_ORIGINS

Required: Yes Description: Comma-separated list of allowed CORS origins

Where to set:

  • Railway (production): https://os.blackroad.systems,https://blackroad.ai,https://blackroad.network
  • Railway (staging): https://staging.blackroad.systems
  • Local: http://localhost:8000,http://localhost:3000

Example:

ALLOWED_ORIGINS=https://os.blackroad.systems,https://blackroad.ai

PORT

Required: No (Railway auto-detects) Default: 8000 Description: HTTP port for the backend server

Where to set:

  • Railway: Not needed (Railway sets $PORT automatically)
  • Local: 8000 (or any available port)

Example:

PORT=8000

Database & Cache

DATABASE_URL

Required: Yes Description: PostgreSQL connection string (sync driver)

Format: postgresql://user:password@host:port/database

Where to set:

  • Railway: Auto-injected via ${{Postgres.DATABASE_URL}}
  • Local: postgresql://user:pass@localhost:5432/blackroad_dev

Example:

DATABASE_URL=postgresql://user:password@localhost:5432/blackroad_dev

How to use Railway reference: In Railway dashboard → Service → Variables:

DATABASE_URL=${{Postgres.DATABASE_URL}}

DATABASE_ASYNC_URL

Required: Yes (for async database operations) Description: PostgreSQL connection string (async driver)

Format: postgresql+asyncpg://user:password@host:port/database

Where to set:

  • Railway: Convert DATABASE_URL to async:

    DATABASE_ASYNC_URL=${{Postgres.DATABASE_URL_ASYNC}}

    Or manually construct:

    # If Railway doesn't provide async URL, derive from sync URL
# Replace 'postgresql://' with 'postgresql+asyncpg://'

  • Local: postgresql+asyncpg://user:pass@localhost:5432/blackroad_dev

Example:

DATABASE_ASYNC_URL=postgresql+asyncpg://user:password@localhost:5432/blackroad_dev

REDIS_URL

Required: Yes Description: Redis connection string for caching and sessions

Format: redis://host:port/db or redis://user:password@host:port/db

Where to set:

  • Railway: Auto-injected via ${{Redis.REDIS_URL}}
  • Local: redis://localhost:6379/0

Example:

REDIS_URL=redis://localhost:6379/0

How to use Railway reference: In Railway dashboard → Service → Variables:

REDIS_URL=${{Redis.REDIS_URL}}

Authentication & Security

ACCESS_TOKEN_EXPIRE_MINUTES

Required: No Default: 30 Description: JWT access token expiration time (in minutes)

Recommended values:

  • Production: 15 - 30 (shorter = more secure)
  • Development: 60 - 120 (longer = less login friction)

Example:

ACCESS_TOKEN_EXPIRE_MINUTES=30

REFRESH_TOKEN_EXPIRE_DAYS

Required: No Default: 7 Description: JWT refresh token expiration time (in days)

Recommended values:

  • Production: 7 - 14
  • Development: 30

Example:

REFRESH_TOKEN_EXPIRE_DAYS=7

WALLET_MASTER_KEY

Required: Yes (for blockchain features) Description: Master key for wallet/blockchain operations

How to generate:

openssl rand -hex 32

⚠️ Security:

  • CRITICAL: Losing this key means losing access to blockchain wallets
  • Backup securely (encrypted password manager, hardware security module)
  • NEVER expose in logs or error messages

Example:

WALLET_MASTER_KEY=your-generated-master-key-here

API Integrations

OPENAI_API_KEY

Required: For AI features (Lucidia, agents) Description: OpenAI API key for GPT models

How to get:

  1. Go to https://platform.openai.com/api-keys
  2. Create new secret key
  3. Copy key (starts with sk-)

Example:

OPENAI_API_KEY=sk-proj-1234567890abcdef...

ANTHROPIC_API_KEY

Required: For Claude integration Description: Anthropic API key for Claude models

How to get:

  1. Go to https://console.anthropic.com/settings/keys
  2. Create new API key
  3. Copy key

Example:

ANTHROPIC_API_KEY=sk-ant-1234567890abcdef...

GITHUB_TOKEN

Required: For GitHub integrations (agents, automation) Description: GitHub Personal Access Token (PAT)

How to get:

  1. Go to https://github.com/settings/tokens
  2. Generate new token (classic or fine-grained)
  3. Required scopes: repo, workflow, read:org

Example:

GITHUB_TOKEN=ghp_1234567890abcdefghijklmnopqrstuvwxyz

STRIPE_SECRET_KEY

Required: For payment features Description: Stripe API secret key

How to get:

  1. Go to https://dashboard.stripe.com/apikeys
  2. Copy "Secret key" (starts with sk_test_ or sk_live_)

⚠️ Use test key for development:

# Development/Staging
STRIPE_SECRET_KEY=sk_test_...

# Production
STRIPE_SECRET_KEY=sk_live_...

STRIPE_PUBLISHABLE_KEY

Required: For frontend payment UI Description: Stripe publishable key (safe to expose in frontend)

Example:

STRIPE_PUBLISHABLE_KEY=pk_test_1234567890abcdef...

AWS_ACCESS_KEY_ID

Required: For AWS S3 storage Description: AWS IAM access key ID

How to get:

  1. AWS Console → IAM → Users → Security Credentials
  2. Create access key
  3. Download/save credentials

Example:

AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE

AWS_SECRET_ACCESS_KEY

Required: For AWS S3 storage Description: AWS IAM secret access key

Example:

AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

AWS_S3_BUCKET

Required: For AWS S3 storage Description: S3 bucket name for file uploads

Example:

AWS_S3_BUCKET=blackroad-uploads-production

AWS_REGION

Required: For AWS S3 storage Default: us-east-1 Description: AWS region for S3 bucket

Example:

AWS_REGION=us-east-1

Infrastructure

CF_API_TOKEN

Required: For Cloudflare automation Description: Cloudflare API token for DNS/cache management

How to get:

  1. Cloudflare dashboard → My Profile → API Tokens
  2. Create token with "Zone.DNS" edit permissions
  3. Copy token

Where to set:

  • GitHub Actions: As secret CF_API_TOKEN
  • Local: Export when running DNS scripts

Example:

CF_API_TOKEN=your-cloudflare-api-token

CF_ZONE_ID

Required: For Cloudflare automation Description: Cloudflare zone ID for a specific domain

How to get:

  1. Cloudflare dashboard → Select domain
  2. Overview page → Right sidebar → Zone ID

Where to set:

  • GitHub Actions: As secret CF_ZONE_ID
  • records.yaml: In domain configuration

Example:

CF_ZONE_ID=1234567890abcdef1234567890abcdef

RAILWAY_TOKEN

Required: For Railway CLI/CI deployments Description: Railway API token for deployments

How to get:

railway login
railway tokens create

Where to set:

  • GitHub Actions: As secret RAILWAY_TOKEN
  • Local: Export when using Railway CLI

Example:

RAILWAY_TOKEN=your-railway-api-token

RAILWAY_SERVICE_ID

Required: For specific service deployments Description: Railway service ID to deploy to

How to get:

  1. Railway dashboard → Service → Settings
  2. Copy Service ID

Where to set:

  • GitHub Actions: As repository variable

Example:

RAILWAY_SERVICE_ID=abc123def456

Deployment

SENTRY_DSN

Required: For error monitoring Description: Sentry Data Source Name for error tracking

How to get:

  1. Go to https://sentry.io
  2. Create new project
  3. Copy DSN from project settings

Example:

SENTRY_DSN=https://1234567890abcdef@o123456.ingest.sentry.io/1234567

SENTRY_ENVIRONMENT

Required: No (if using SENTRY_DSN) Default: Uses ENVIRONMENT value Description: Sentry environment tag

Example:

SENTRY_ENVIRONMENT=production

Observability

LOG_LEVEL

Required: No Default: INFO Valid values: DEBUG, INFO, WARNING, ERROR, CRITICAL Description: Application logging level

Recommended:

  • Production: WARNING or INFO
  • Staging: INFO or DEBUG
  • Development: DEBUG

Example:

LOG_LEVEL=INFO

Where to Set Variables

Railway (Production & Staging)

  1. Go to Railway dashboard → Your project
  2. Select service (e.g., backend)
  3. Go to Variables tab
  4. Click New Variable
  5. Enter name and value
  6. Click Add

Railway Reference Variables: Use ${{ServiceName.VARIABLE}} to reference values from other services:

DATABASE_URL=${{Postgres.DATABASE_URL}}
REDIS_URL=${{Redis.REDIS_URL}}

Shared Variables: For variables used across services, use Shared Variables:

  1. Variables tab → Shared Variables
  2. Add variable (e.g., SECRET_KEY)
  3. All services can access

GitHub Actions

  1. Go to repository → Settings → Secrets and variables → Actions
  2. Click New repository secret
  3. Enter name and value
  4. Click Add secret

Required GitHub Secrets:

  • RAILWAY_TOKEN - For Railway deployments
  • CF_API_TOKEN - For DNS automation
  • SENTRY_DSN - For error monitoring (optional)

How to use in workflows:

env:
  RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}

Local Development

  1. Copy environment template:

    cp backend/.env.example backend/.env

  2. Edit .env file with your local values:

    nano backend/.env  # or use your preferred editor

  3. The .env file is gitignored - safe to add real values

  4. FastAPI automatically loads .env via python-dotenv

⚠️ Never commit .env files to git!

Security Best Practices

1. Secret Generation

  • Always use cryptographically secure random generators
  • Minimum 32 characters for secrets
  • Use different secrets per environment

Good:

openssl rand -hex 32
python -c "import secrets; print(secrets.token_hex(32))"

Bad:

# Don't use predictable values
SECRET_KEY=password123
SECRET_KEY=my-app-secret

2. Secret Storage

  • ✅ Railway environment variables (encrypted at rest)
  • ✅ GitHub Actions secrets (encrypted)
  • ✅ .env files (gitignored)
  • ✅ Password managers (1Password, LastPass, Bitwarden)
  • ❌ NEVER commit secrets to git
  • ❌ NEVER hardcode in source code
  • ❌ NEVER expose in logs or error messages

3. Secret Rotation

  • Rotate SECRET_KEY quarterly
  • Rotate API keys after suspected compromise
  • Update credentials after team member departure
  • Keep backups of old secrets (for rollback)

4. Principle of Least Privilege

  • Give each service only the permissions it needs
  • Use separate database users for different services
  • Use read-only API keys where possible
  • Limit token scopes (GitHub, Stripe, etc.)

5. Verification

Before deploying to production:

  • All required variables are set
  • No placeholder values (e.g., REPLACE_ME)
  • Secrets are unique per environment
  • DEBUG=False in production
  • CORS origins match production domains
  • Database backups are configured

Quick Start Templates

Production Railway (backend service)

# Core
ENVIRONMENT=production
DEBUG=False
SECRET_KEY=[generate-unique-32-char-string]
API_BASE_URL=https://os.blackroad.systems
FRONTEND_URL=https://os.blackroad.systems
ALLOWED_ORIGINS=https://os.blackroad.systems,https://blackroad.ai

# Database (auto-injected by Railway)
DATABASE_URL=${{Postgres.DATABASE_URL}}
DATABASE_ASYNC_URL=${{Postgres.DATABASE_URL_ASYNC}}
REDIS_URL=${{Redis.REDIS_URL}}

# Auth
ACCESS_TOKEN_EXPIRE_MINUTES=30
REFRESH_TOKEN_EXPIRE_DAYS=7
WALLET_MASTER_KEY=[generate-unique-32-char-string]

# AI (add when ready)
# OPENAI_API_KEY=sk-proj-...
# ANTHROPIC_API_KEY=sk-ant-...

# Observability (add when ready)
# SENTRY_DSN=https://...
# LOG_LEVEL=WARNING

Local Development (.env)

# Core
ENVIRONMENT=development
DEBUG=True
SECRET_KEY=local-dev-secret-key-not-for-production
API_BASE_URL=http://localhost:8000
FRONTEND_URL=http://localhost:8000
ALLOWED_ORIGINS=http://localhost:8000,http://localhost:3000

# Database (Docker Compose)
DATABASE_URL=postgresql://blackroad:blackroad@localhost:5432/blackroad_dev
DATABASE_ASYNC_URL=postgresql+asyncpg://blackroad:blackroad@localhost:5432/blackroad_dev
REDIS_URL=redis://localhost:6379/0

# Auth
ACCESS_TOKEN_EXPIRE_MINUTES=120
REFRESH_TOKEN_EXPIRE_DAYS=30
WALLET_MASTER_KEY=local-dev-wallet-key

# AI (optional - use your own keys)
# OPENAI_API_KEY=sk-...
# ANTHROPIC_API_KEY=sk-ant-...

GitHub Actions Secrets

# Required
RAILWAY_TOKEN=[get-from-railway-cli]
CF_API_TOKEN=[get-from-cloudflare]

# Optional
SENTRY_DSN=[get-from-sentry]

Validation Script

Use this script to validate your environment variables:

#!/bin/bash
# File: scripts/validate_env.sh

set -e

echo "Validating environment variables..."

# Check required variables
REQUIRED_VARS=(
  "ENVIRONMENT"
  "SECRET_KEY"
  "DATABASE_URL"
  "REDIS_URL"
  "API_BASE_URL"
  "FRONTEND_URL"
  "ALLOWED_ORIGINS"
)

MISSING_VARS=()

for VAR in "${REQUIRED_VARS[@]}"; do
  if [ -z "${!VAR}" ]; then
    MISSING_VARS+=("$VAR")
  fi
done

if [ ${#MISSING_VARS[@]} -gt 0 ]; then
  echo "❌ Missing required environment variables:"
  printf '  - %s\n' "${MISSING_VARS[@]}"
  exit 1
fi

# Check SECRET_KEY length
if [ ${#SECRET_KEY} -lt 32 ]; then
  echo "❌ SECRET_KEY must be at least 32 characters"
  exit 1
fi

# Check DEBUG in production
if [ "$ENVIRONMENT" = "production" ] && [ "$DEBUG" = "True" ]; then
  echo "⚠️  WARNING: DEBUG=True in production environment!"
  exit 1
fi

echo "✅ Environment variables validated successfully!"

Run before deploy:

chmod +x scripts/validate_env.sh
source backend/.env && ./scripts/validate_env.sh

Troubleshooting

Variable Not Loading

Problem: Application doesn't see environment variable

Solutions:

  1. Railway: Check service Variables tab - is variable set?
  2. Local: Is .env file in correct location (backend/.env)?
  3. Restart: Restart application after changing variables
  4. Syntax: Check for typos in variable names

Database Connection Fails

Problem: DatabaseConnectionError or similar

Solutions:

  1. Check DATABASE_URL format is correct
  2. Railway: Verify Postgres plugin is attached
  3. Local: Check Docker Compose is running (docker-compose ps)
  4. Check database credentials are correct

CORS Errors

Problem: Frontend can't call API (CORS error in browser console)

Solutions:

  1. Check ALLOWED_ORIGINS includes frontend domain
  2. Include protocol: https:// not just domain.com
  3. No trailing slash: https://domain.com not https://domain.com/
  4. Railway: Wait 1-2 minutes for variable updates to apply

This document is the single source of truth for environment variables. Keep it updated as new variables are added.

Where AI meets the open road. 🛣️