the_order/docs/configuration/ENVIRONMENT_VARIABLES.md

Environment Variables

This document describes all environment variables used across The Order monorepo services and applications.

Table of Contents

• Required Variables
• Optional Variables
• Development Variables
• Service-Specific Variables
• Configuration Examples

---

Required Variables

These variables must be set for the application to function properly.

Database

DATABASE_URL

• Type: String (URL)
• Required: Yes
• Description: PostgreSQL connection string
• Format: postgresql://user:password@host:port/database
• Example: postgresql://postgres:password@localhost:5432/theorder
• Used By: All services

Storage

STORAGE_BUCKET

• Type: String
• Required: Yes
• Description: S3/GCS bucket name for document storage
• Example: the-order-documents-prod
• Used By: Dataroom, Intake services

STORAGE_TYPE

• Type: Enum (s3 | gcs)
• Required: No (default: s3)
• Description: Storage provider type
• Example: s3
• Used By: Dataroom, Intake services

STORAGE_REGION

• Type: String
• Required: No (default: us-east-1)
• Description: AWS region for S3 or GCS region
• Example: us-east-1
• Used By: Dataroom, Intake services

AWS_ACCESS_KEY_ID

• Type: String
• Required: No (uses IAM role if not provided)
• Description: AWS access key ID for S3 access
• Used By: Storage client

AWS_SECRET_ACCESS_KEY

• Type: String
• Required: No (uses IAM role if not provided)
• Description: AWS secret access key for S3 access
• Used By: Storage client

Key Management System (KMS)

KMS_KEY_ID

• Type: String
• Required: Yes
• Description: KMS key identifier for encryption and signing
• Example: arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012
• Used By: Identity service, Crypto package

KMS_TYPE

• Type: Enum (aws | gcp)
• Required: No (default: aws)
• Description: KMS provider type
• Example: aws
• Used By: Identity service, Crypto package

KMS_REGION

• Type: String
• Required: No (default: us-east-1)
• Description: KMS region
• Example: us-east-1
• Used By: Identity service, Crypto package

Authentication

JWT_SECRET

• Type: String
• Required: Yes
• Description: Secret key for JWT token signing and verification (minimum 32 characters)
• Example: your-super-secret-jwt-key-minimum-32-chars-long
• Used By: All services (for JWT authentication)

VC_ISSUER_DID

• Type: String
• Required: No (or VC_ISSUER_DOMAIN must be set)
• Description: DID (Decentralized Identifier) for verifiable credential issuance
• Example: did:web:the-order.example.com
• Used By: Identity service

VC_ISSUER_DOMAIN

• Type: String
• Required: No (or VC_ISSUER_DID must be set)
• Description: Domain for did:web DID resolution (will be converted to did:web:{domain})
• Example: the-order.example.com
• Used By: Identity service

EIDAS_PROVIDER_URL

• Type: String (URL)
• Required: No
• Description: eIDAS provider URL for qualified signatures
• Example: https://eidas-provider.example.com
• Used By: Identity service, eIDAS bridge

EIDAS_API_KEY

• Type: String
• Required: No
• Description: API key for eIDAS provider
• Example: eidas-api-key-here
• Used By: Identity service, eIDAS bridge

ENTRA_TENANT_ID

• Type: String
• Required: No
• Description: Azure AD tenant ID for Microsoft Entra VerifiedID
• Example: 12345678-1234-1234-1234-123456789012
• Used By: Identity service

ENTRA_CLIENT_ID

• Type: String
• Required: No
• Description: Azure AD application (client) ID for Microsoft Entra VerifiedID
• Example: 87654321-4321-4321-4321-210987654321
• Used By: Identity service

ENTRA_CLIENT_SECRET

• Type: String
• Required: No
• Description: Azure AD client secret for Microsoft Entra VerifiedID
• Example: client-secret-value
• Used By: Identity service

ENTRA_CREDENTIAL_MANIFEST_ID

• Type: String
• Required: No
• Description: Credential manifest ID from Azure Verified ID portal
• Example: urn:uuid:12345678-1234-1234-1234-123456789012
• Used By: Identity service

AZURE_LOGIC_APPS_WORKFLOW_URL

• Type: String (URL)
• Required: No
• Description: Azure Logic Apps workflow URL
• Example: https://your-logic-app.azurewebsites.net
• Used By: Identity service, workflows

AZURE_LOGIC_APPS_ACCESS_KEY

• Type: String
• Required: No
• Description: Azure Logic Apps access key (if not using managed identity)
• Example: access-key-here
• Used By: Identity service, workflows

AZURE_LOGIC_APPS_MANAGED_IDENTITY_CLIENT_ID

• Type: String
• Required: No
• Description: Managed identity client ID for Logic Apps authentication
• Example: managed-identity-client-id
• Used By: Identity service, workflows

---

Optional Variables

OpenID Connect (OIDC)

OIDC_ISSUER

• Type: String (URL)
• Required: No
• Description: OIDC issuer URL
• Example: https://auth.example.com
• Used By: Identity service, Shared auth middleware

OIDC_CLIENT_ID

• Type: String
• Required: No
• Description: OIDC client ID
• Example: the-order-client
• Used By: Identity service, Shared auth middleware

OIDC_CLIENT_SECRET

• Type: String
• Required: No
• Description: OIDC client secret
• Example: client-secret-here
• Used By: Identity service, Shared auth middleware

Monitoring & Observability

OTEL_EXPORTER_OTLP_ENDPOINT

• Type: String (URL)
• Required: No
• Description: OpenTelemetry collector endpoint for traces
• Example: http://otel-collector:4318
• Used By: Monitoring package

OTEL_SERVICE_NAME

• Type: String
• Required: No
• Description: Service name for OpenTelemetry tracing
• Example: identity-service
• Used By: Monitoring package

Payment Gateway

PAYMENT_GATEWAY_API_KEY

• Type: String
• Required: No
• Description: Stripe API key for payment processing
• Example: sk_live_... or sk_test_...
• Used By: Finance service

PAYMENT_GATEWAY_WEBHOOK_SECRET

• Type: String
• Required: No
• Description: Stripe webhook secret for verifying webhook signatures
• Example: whsec_...
• Used By: Finance service

OCR Service

OCR_SERVICE_URL

• Type: String (URL)
• Required: No
• Description: External OCR service URL (if not set, uses local Tesseract.js)
• Example: https://ocr-service.example.com
• Used By: Intake service, OCR package

OCR_SERVICE_API_KEY

• Type: String
• Required: No
• Description: API key for external OCR service
• Example: ocr-api-key-here
• Used By: Intake service, OCR package

Machine Learning

ML_CLASSIFICATION_SERVICE_URL

• Type: String (URL)
• Required: No
• Description: ML service URL for document classification
• Example: https://ml-service.example.com
• Used By: Intake service, Workflows

ML_CLASSIFICATION_API_KEY

• Type: String
• Required: No
• Description: API key for ML classification service
• Example: ml-api-key-here
• Used By: Intake service, Workflows

Caching

REDIS_URL

• Type: String (URL)
• Required: No
• Description: Redis connection string for caching
• Example: redis://localhost:6379 or redis://:password@host:6379
• Used By: (Future implementation)

Message Queue

MESSAGE_QUEUE_URL

• Type: String (URL)
• Required: No
• Description: Message queue connection string (e.g., RabbitMQ, Kafka)
• Example: amqp://localhost:5672 or kafka://localhost:9092
• Used By: (Future implementation)

Google Cloud Platform (GCP)

GCP_PROJECT_ID

• Type: String
• Required: No
• Description: GCP project ID (if using GCS storage)
• Example: the-order-project
• Used By: Storage client (GCS mode)

GCP_KEY_FILE

• Type: String (file path)
• Required: No
• Description: Path to GCP service account key file (if using GCS storage)
• Example: /path/to/service-account-key.json
• Used By: Storage client (GCS mode)

---

Development Variables

NODE_ENV

• Type: Enum (development | staging | production)
• Required: No (default: development)
• Description: Environment mode
• Used By: All services

PORT

• Type: Number
• Required: No (default: 3000)
• Description: Server port number
• Example: 4001 (Intake), 4002 (Identity), 4003 (Finance), 4004 (Dataroom)
• Used By: All services

LOG_LEVEL

• Type: Enum (fatal | error | warn | info | debug | trace)
• Required: No (default: info)
• Description: Logging verbosity level
• Used By: All services

SWAGGER_SERVER_URL

• Type: String (URL)
• Required: No
• Description: Base URL for Swagger/OpenAPI documentation
• Example: http://localhost:4002 (Identity service)
• Note: In development, defaults to http://localhost:{PORT} if not set
• Used By: All services (for API documentation)

CORS_ORIGIN

• Type: String (comma-separated)
• Required: No
• Description: Allowed CORS origins (comma-separated list)
• Example: http://localhost:3000,https://app.example.com
• Note: In development, defaults to http://localhost:3000 if not set
• Used By: All services

---

Service-Specific Variables

Identity Service

• DATABASE_URL (required)
• KMS_KEY_ID (required)
• KMS_TYPE (optional)
• KMS_REGION (optional)
• JWT_SECRET (required)
• VC_ISSUER_DID or VC_ISSUER_DOMAIN (required)
• OIDC_ISSUER (optional)
• OIDC_CLIENT_ID (optional)
• OIDC_CLIENT_SECRET (optional)
• PORT (optional, default: 4002)
• SWAGGER_SERVER_URL (optional)

Intake Service

• DATABASE_URL (required)
• STORAGE_BUCKET (required)
• STORAGE_TYPE (optional)
• STORAGE_REGION (optional)
• OCR_SERVICE_URL (optional)
• OCR_SERVICE_API_KEY (optional)
• ML_CLASSIFICATION_SERVICE_URL (optional)
• ML_CLASSIFICATION_API_KEY (optional)
• PORT (optional, default: 4001)
• SWAGGER_SERVER_URL (optional)

Finance Service

• DATABASE_URL (required)
• PAYMENT_GATEWAY_API_KEY (optional)
• PAYMENT_GATEWAY_WEBHOOK_SECRET (optional)
• PORT (optional, default: 4003)
• SWAGGER_SERVER_URL (optional)

Dataroom Service

• DATABASE_URL (required)
• STORAGE_BUCKET (required)
• STORAGE_TYPE (optional)
• STORAGE_REGION (optional)
• PORT (optional, default: 4004)
• SWAGGER_SERVER_URL (optional)

---

Configuration Examples

Development Environment

# .env.development
NODE_ENV=development
LOG_LEVEL=debug

# Database
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/theorder_dev

# Storage
STORAGE_BUCKET=the-order-documents-dev
STORAGE_TYPE=s3
STORAGE_REGION=us-east-1

# KMS
KMS_KEY_ID=arn:aws:kms:us-east-1:123456789012:key/dev-key
KMS_TYPE=aws
KMS_REGION=us-east-1

# Authentication
JWT_SECRET=development-jwt-secret-key-minimum-32-characters-long
VC_ISSUER_DOMAIN=localhost:4002

# CORS
CORS_ORIGIN=http://localhost:3000

# Swagger
SWAGGER_SERVER_URL=http://localhost:4002

Production Environment

# .env.production
NODE_ENV=production
LOG_LEVEL=info

# Database
DATABASE_URL=postgresql://user:password@db.example.com:5432/theorder

# Storage
STORAGE_BUCKET=the-order-documents-prod
STORAGE_TYPE=s3
STORAGE_REGION=us-east-1

# KMS
KMS_KEY_ID=arn:aws:kms:us-east-1:123456789012:key/prod-key
KMS_TYPE=aws
KMS_REGION=us-east-1

# Authentication
JWT_SECRET=${JWT_SECRET}  # From secrets manager
VC_ISSUER_DID=did:web:the-order.example.com

# OIDC
OIDC_ISSUER=https://auth.example.com
OIDC_CLIENT_ID=the-order-prod
OIDC_CLIENT_SECRET=${OIDC_CLIENT_SECRET}  # From secrets manager

# Payment Gateway
PAYMENT_GATEWAY_API_KEY=${STRIPE_API_KEY}  # From secrets manager
PAYMENT_GATEWAY_WEBHOOK_SECRET=${STRIPE_WEBHOOK_SECRET}  # From secrets manager

# Monitoring
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
OTEL_SERVICE_NAME=identity-service

# CORS
CORS_ORIGIN=https://app.example.com,https://admin.example.com

# Swagger
SWAGGER_SERVER_URL=https://api.example.com

Docker Compose Example

services:
  identity:
    environment:
      - NODE_ENV=development
      - DATABASE_URL=postgresql://postgres:postgres@db:5432/theorder
      - KMS_KEY_ID=arn:aws:kms:us-east-1:123456789012:key/dev-key
      - JWT_SECRET=development-jwt-secret-key-minimum-32-characters-long
      - VC_ISSUER_DOMAIN=localhost:4002
      - PORT=4002

---

Security Best Practices

1. Never commit secrets to version control

   • Use .env files (gitignored) for local development
   • Use secrets management services (AWS Secrets Manager, HashiCorp Vault) for production

2. Use strong JWT secrets

   • Minimum 32 characters
   • Use cryptographically random strings
   • Rotate regularly

3. Restrict CORS origins

   • Only include trusted domains
   • Never use * in production

4. Use IAM roles when possible

   • Prefer IAM roles over access keys for AWS services
   • Reduces risk of credential exposure

5. Rotate credentials regularly

   • Set up rotation schedules for API keys
   • Monitor for credential leaks

---

Validation

All environment variables are validated at application startup using Zod schemas in packages/shared/src/env.ts. Invalid or missing required variables will cause the application to fail to start with a clear error message.

---

See Also

• Architecture Documentation
• Deployment Guide
• Security Documentation