RitualOSDocs
referenceintermediate

ENVIRONMENT_VARIABLES

Documentation for ENVIRONMENT_VARIABLES

5 min read
v3.0
reference

RitualOS Environment Variables Reference

Updated: March 13, 2026
Architecture: Consolidated single service (id.ritualos.com) with internal ledger module
Status: All APIs merged - API_SERVICE_URL and LEDGER_SERVICE_URL deprecated

Overview

After consolidation, RitualOS uses a single backend service with clear internal modules. All services only need to configure ID_SERVICE_URL.

Security Notes:

  • Never commit .env files to version control
  • Use strong secrets (minimum 32 characters for sensitive values)
  • Rotate secrets regularly (recommended: 90 days for production)
  • Use Vercel Environment Variables for production

Global Variables (All Consuming Services)

VariableRequiredDescriptionExampleNotes
NODE_ENVYesEnvironment (development/staging/production)productionAffects logging, optimization
DATABASE_URLYesPostgreSQL connection stringpostgresql://user:pass@localhost:5432/dbnameService-specific database
ID_SERVICE_URLYesConsolidated ID service endpointhttps://id.ritualos.comOAuth, auth, all backend APIs, ledger module
SESSION_SECRETYesSession encryption key (32+ chars)secure-random-32-char-keyMinimum 32 characters
JWT_SECRETYesJWT signing key (32+ chars)secure-random-32-char-keyMinimum 32 characters

Deprecated Variables (Remove from all services):

  • ❌ API_SERVICE_URL - Moved to id.ritualos.com
  • ❌ LEDGER_SERVICE_URL - Ledger is now internal module

Per-Service Variables

id.ritualos.com (Consolidated Service)

VariableRequiredDescriptionExampleSecurity
DATABASE_URLYesPostgreSQL connectionpostgresql://ritualos:ritualos_dev_password@localhost:5432/ritualos_idEncrypt at rest
JWT_SECRETYesJWT session signing (32+ chars)abcdefghijklmnopqrstuvwxyz123456Minimum 32 chars
SESSION_SECRETYesSession encryption (32+ chars)abcdefghijklmnopqrstuvwxyz123456Minimum 32 chars
ENCRYPTION_KEYYesCredential encryption (32-byte hex)1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o632 bytes hex
ISSUER_API_KEYYesOAuth issuer key (id service only)rit_sk_prod_abc123...Start with rit_sk_
PARTNER_WEBHOOK_SECRETNoSecret for signing partner webhookswhsec_abc123...For secure event delivery
CORS_ORIGINNoCORS allowed originshttp://localhost:3000Comma-separated for prod
PORTNoServer port3000Default: 3000
NODE_ENVNoEnvironmentdevelopmentdevelopment/production

Development .env Example:

DATABASE_URL=postgresql://ritualos:ritualos_dev_password@localhost:5432/ritualos_id
JWT_SECRET=development-secret-key-32-chars-long-minimum
SESSION_SECRET=session-secret-key-32-chars-long-minimum
ENCRYPTION_KEY=1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6
ISSUER_API_KEY=rit_sk_dev_test_key_123456789
CORS_ORIGIN=http://localhost:3000,http://localhost:3001
PORT=3000
NODE_ENV=development

Consolidated Service Endpoints:

  • OAuth: /api/oauth/*
  • Authentication: /api/auth/*
  • User Profile: /api/me
  • Credentials: /api/credentials/*
  • Badges: /api/badges/*
  • Cards: /api/cards/*
  • Partners: /api/partners/*
  • Admin: /api/admin/*
  • Ledger Receipts: /api/ledger/receipts/*
  • Ledger Health: /api/ledger/health

home.ritualos.com

Marketing and documentation site. OAuth config is optional (used when home needs auth flows).

VariableRequiredDescriptionExampleNotes
ID_SERVICE_URLNoID service URL (for OAuth)http://localhost:7000Defaults to localhost:7000 in dev
NEXT_PUBLIC_ID_SERVICE_URLNoPublic ID service URLhttp://localhost:7000For client-side redirects
OAUTH_CLIENT_IDIf using authOAuth client identifierhomePre-registered with ID service
OAUTH_CLIENT_SECRETIf using authOAuth client secret...From pnpm oauth:register-clients -- --client home

Development .env Example (when using OAuth):

ID_SERVICE_URL=http://localhost:7000
NEXT_PUBLIC_ID_SERVICE_URL=http://localhost:7000
OAUTH_CLIENT_ID=home
OAUTH_CLIENT_SECRET=<from oauth:register-clients --client home>

demo.ritualos.com

Reference template app for OAuth integration. Port 3010 locally.

VariableRequiredDescriptionExampleNotes
ID_SERVICE_URLYesID service URLhttp://localhost:7000
NEXT_PUBLIC_ID_SERVICE_URLYesPublic ID service URLhttp://localhost:7000
OAUTH_CLIENT_IDYesOAuth client identifierdemoPre-registered
OAUTH_CLIENT_SECRETYesOAuth client secret...From pnpm oauth:register-clients -- --client demo
SESSION_SECRETYesSession cookie signing (32+ chars)...Minimum 32 characters

Development .env Example:

ID_SERVICE_URL=http://localhost:7000
NEXT_PUBLIC_ID_SERVICE_URL=http://localhost:7000
OAUTH_CLIENT_ID=demo
OAUTH_CLIENT_SECRET=<from oauth:register-clients --client demo>
SESSION_SECRET=<min-32-char-secret>

path.ritualos.com

VariableRequiredDescriptionExampleNotes
DATABASE_URLYesPostgreSQL connectionpostgresql://ritualos_Path:password@localhost:5434/ritualos_gamePort 5434
SESSION_SECRETYesSession encryption (32+ chars)abcdefghijklmnopqrstuvwxyz123456Minimum 32 characters
JWT_SECRETYesJWT signing key (32+ chars)abcdefghijklmnopqrstuvwxyz123456Minimum 32 characters
OAUTH_CLIENT_IDYesOAuth client identifierpathPre-registered with ID service
OAUTH_CLIENT_SECRETYesOAuth client secretrit_sc_abc123...From OAuth registration
ID_SERVICE_URLYesConsolidated ID servicehttp://localhost:7000Only this service URL needed

Development .env Example:

DATABASE_URL=postgresql://ritualos_Path:password@localhost:5434/ritualos_game
SESSION_SECRET=path-dev-session-secret-32-chars-minimum
JWT_SECRET=path-dev-jwt-secret-32-chars-minimum
OAUTH_CLIENT_ID=path
OAUTH_CLIENT_SECRET=rit_sc_dev_secret_from_registration
ID_SERVICE_URL=http://localhost:7000
NODE_ENV=development
PORT=4000

scroll.ritualos.com

VariableRequiredDescriptionExampleNotes
DATABASE_URLYesPostgreSQL connectionpostgresql://ritualos_Scroll:password@localhost:5433/ritualos_scrollPort 5433
SESSION_SECRETYesSession encryption (32+ chars)abcdefghijklmnopqrstuvwxyz123456Minimum 32 characters
JWT_SECRETYesJWT signing key (32+ chars)abcdefghijklmnopqrstuvwxyz123456Minimum 32 characters
OAUTH_CLIENT_IDYesOAuth client identifierscrollPre-registered
OAUTH_CLIENT_SECRETYesOAuth client secretrit_sc_abc123...From OAuth registration
ID_SERVICE_URLYesConsolidated ID servicehttp://localhost:7000Only this service URL needed

Development .env Example:

DATABASE_URL=postgresql://ritualos_Scroll:password@localhost:5433/ritualos_scroll
SESSION_SECRET=scroll-dev-session-secret-32-chars-minimum
JWT_SECRET=scroll-dev-jwt-secret-32-chars-minimum
OAUTH_CLIENT_ID=scroll
OAUTH_CLIENT_SECRET=rit_sc_dev_secret_from_registration
ID_SERVICE_URL=http://localhost:7000
NODE_ENV=development
PORT=3003

learn.ritualos.com

VariableRequiredDescriptionExampleNotes
DATABASE_URLYesPostgreSQL connectionpostgresql://ritualos_Learn:password@localhost:5435/ritualos_learnPort 5435
SESSION_SECRETYesSession encryption (32+ chars)abcdefghijklmnopqrstuvwxyz123456Minimum 32 characters
JWT_SECRETYesJWT signing key (32+ chars)abcdefghijklmnopqrstuvwxyz123456Minimum 32 characters
OAUTH_CLIENT_IDYesOAuth client identifierlearnPre-registered
OAUTH_CLIENT_SECRETYesOAuth client secretrit_sc_abc123...From OAuth registration
ID_SERVICE_URLYesConsolidated ID servicehttp://localhost:7000Only this service URL needed

Development .env Example:

DATABASE_URL=postgresql://ritualos_Learn:password@localhost:5435/ritualos_learn
SESSION_SECRET=learn-dev-session-secret-32-chars-minimum
JWT_SECRET=learn-dev-jwt-secret-32-chars-minimum
OAUTH_CLIENT_ID=learn
OAUTH_CLIENT_SECRET=rit_sc_dev_secret_from_registration
ID_SERVICE_URL=http://localhost:7000
NODE_ENV=development
PORT=3005

governance.ritualos.com

VariableRequiredDescriptionExampleNotes
DATABASE_URLYesPostgreSQL connectionpostgresql://ritualos_Governance:password@localhost:5436/ritualos_governancePort 5436
SESSION_SECRETYesSession encryption (32+ chars)abcdefghijklmnopqrstuvwxyz123456Minimum 32 characters
JWT_SECRETYesJWT signing key (32+ chars)abcdefghijklmnopqrstuvwxyz123456Minimum 32 characters
OAUTH_CLIENT_IDYesOAuth client identifiergovernancePre-registered
OAUTH_CLIENT_SECRETYesOAuth client secretrit_sc_abc123...From OAuth registration
ID_SERVICE_URLYesConsolidated ID servicehttp://localhost:7000Only this service URL needed

Development .env Example:

DATABASE_URL=postgresql://ritualos_Governance:password@localhost:5436/ritualos_governance
SESSION_SECRET=governance-dev-session-secret-32-chars-minimum
JWT_SECRET=governance-dev-jwt-secret-32-chars-minimum
OAUTH_CLIENT_ID=governance
OAUTH_CLIENT_SECRET=rit_sc_dev_secret_from_registration
ID_SERVICE_URL=http://localhost:7000
NODE_ENV=development
PORT=3007

guild.ritualos.com

VariableRequiredDescriptionExampleNotes
DATABASE_URLYesPostgreSQL connectionpostgresql://ritualos_Guild:password@localhost:5437/ritualos_guildPort 5437
SESSION_SECRETYesSession encryption (32+ chars)abcdefghijklmnopqrstuvwxyz123456Minimum 32 characters
JWT_SECRETYesJWT signing key (32+ chars)abcdefghijklmnopqrstuvwxyz123456Minimum 32 characters
OAUTH_CLIENT_IDYesOAuth client identifierguildPre-registered
OAUTH_CLIENT_SECRETYesOAuth client secretrit_sc_abc123...From OAuth registration
ID_SERVICE_URLYesConsolidated ID servicehttp://localhost:7000Only this service URL needed

Development .env Example:

DATABASE_URL=postgresql://ritualos_Guild:password@localhost:5437/ritualos_guild
SESSION_SECRET=guild-dev-session-secret-32-chars-minimum
JWT_SECRET=guild-dev-jwt-secret-32-chars-minimum
OAUTH_CLIENT_ID=guild
OAUTH_CLIENT_SECRET=rit_sc_dev_secret_from_registration
ID_SERVICE_URL=http://localhost:7000
NODE_ENV=development
PORT=3006

market.ritualos.com

VariableRequiredDescriptionExampleNotes
DATABASE_URLYesPostgreSQL connectionpostgresql://ritualos_Market:password@localhost:5440/ritualos_marketPort 5440
SESSION_SECRETYesSession encryption (32+ chars)abcdefghijklmnopqrstuvwxyz123456Minimum 32 characters
JWT_SECRETYesJWT signing key (32+ chars)abcdefghijklmnopqrstuvwxyz123456Minimum 32 characters
OAUTH_CLIENT_IDYesOAuth client identifiermarketPre-registered
OAUTH_CLIENT_SECRETYesOAuth client secretrit_sc_abc123...From OAuth registration
ID_SERVICE_URLYesConsolidated ID servicehttp://localhost:7000Only this service URL needed

Development .env Example:

DATABASE_URL=postgresql://ritualos_Market:password@localhost:5440/ritualos_market
SESSION_SECRET=market-dev-session-secret-32-chars-minimum
JWT_SECRET=market-dev-jwt-secret-32-chars-minimum
OAUTH_CLIENT_ID=market
OAUTH_CLIENT_SECRET=rit_sc_dev_secret_from_registration
ID_SERVICE_URL=http://localhost:7000
NODE_ENV=development
PORT=3009

realm.ritualos.com (Vite + Vue)

VariableRequiredDescriptionExampleNotes
VITE_ID_SERVICE_URLYesFrontend env - ID service URLhttp://localhost:3000Only this service URL needed
DATABASE_URLYesPostgreSQL connection (backend)postgresql://ritualos_Realm:password@localhost:5439/ritualos_realmPort 5439
SESSION_SECRETYesSession encryption (32+ chars)abcdefghijklmnopqrstuvwxyz123456Minimum 32 characters
JWT_SECRETYesJWT signing key (32+ chars)abcdefghijklmnopqrstuvwxyz123456Minimum 32 characters

Development .env Example:

VITE_ID_SERVICE_URL=http://localhost:7000
DATABASE_URL=postgresql://ritualos_Realm:password@localhost:5439/ritualos_realm
SESSION_SECRET=realm-dev-session-secret-32-chars-minimum
JWT_SECRET=realm-dev-jwt-secret-32-chars-minimum
NODE_ENV=development
PORT=3008

ritualos.com (Portal)

No environment variables needed - static site with no backend.

Production Database URLs (Vercel + Neon)

When deploying to Vercel, replace localhost DATABASE_URL with Neon database URLs:

Neon Database URL Format

DATABASE_URL=postgresql://user:password@ep-cool-name.aws.us-east-1.aws.neon.tech/dbname?sslmode=require

Vercel Environment Variables Checklist

For each service in Vercel dashboard:

Required Variables:

  • ID_SERVICE_URL = https://id.ritualos.com
  • DATABASE_URL = PostgreSQL connection string
  • JWT_SECRET = Secure random string (32+ chars)
  • SESSION_SECRET = Secure random string (32+ chars)
  • NODE_ENV = production

Variables to Remove:

  • Delete API_SERVICE_URL (if present)
  • Delete LEDGER_SERVICE_URL (if present)

Secret Management Best Practices

Development

  1. Create .env file in each service directory
  2. Copy from .env.example (if available)
  3. Set required variables with development values
  4. Never commit .env files (add to .gitignore)

Production (Vercel)

  1. Create Neon databases for each service (9 total)
  2. Add DATABASE_URL to Vercel Environment Variables
  3. Add sensitive variables (JWT_SECRET, SESSION_SECRET, etc.) to Vercel
  4. Use strong, unique secrets for each environment
  5. Enable Vercel's secret encryption

Secret Rotation

  • JWT_SECRET / SESSION_SECRET: Rotate every 90 days
  • ISSUER_API_KEY: Rotate every 90 days
  • OAUTH_CLIENT_SECRET: Rotate if compromised

Troubleshooting

Database Connection Failed

# Verify Docker database is running
docker ps | findstr ritualos

# Test connection manually
psql postgresql://ritualos:password@localhost:5432/ritualos_id

# Check DATABASE_URL format
# Must include: protocol://user:password@host:port/database

OAuth Flow Failed

# Verify ID service is running
docker ps | findstr ritualos-id

# Check OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET
# Must match values registered in id.ritualos.com database

# Test OAuth endpoint
curl http://localhost:3000/api/oauth/authorize

Ledger Operations Not Working

# Verify ledger module is running as part of id.ritualos.com
curl http://localhost:3000/api/ledger/health

# Check ledger receipt endpoint
curl http://localhost:3000/api/ledger/receipts?identityId=test

Missing Environment Variable

# Check .env file exists
ls -la path.ritualos.com/.env

# Check .gitignore contains .env
type path.ritualos.com\.gitignore | findstr ".env"

# Add to Vercel Environment Variables
# In Vercel Dashboard: Project Settings > Environment Variables

Next Steps

  1. Development Setup:

    • Copy environment variables from this document
    • Create .env files for each service
    • Start Docker databases
    • Test connections to id.ritualos.com

  2. Production Setup:

    • Create Neon databases (9 projects)
    • Add DATABASE_URL to Vercel for each service
    • Add ID_SERVICE_URL=https://id.ritualos.com to all services
    • Remove API_SERVICE_URL and LEDGER_SERVICE_URL from all services
    • Test production connections

Last Updated: February 2, 2026
Architecture: Consolidated id.ritualos.com with internal ledger module

Last updated: 3/13/2026

Edit this page on GitHub →