Environment Variables

The CGIAR Risk Intelligence Tool uses environment variables to configure both the API (NestJS) and Web (Next.js) packages. This guide documents all required and optional variables.

API Environment Variables

The API package (packages/api/) requires environment variables for database connections, AWS service integration, and runtime configuration.

Local Development (.env file)

For local development, create a .env file in packages/api/:

cp packages/api/.env.example packages/api/.env

Never commit .env files to version control. Add .env to .gitignore to prevent accidental commits of sensitive credentials.

API Variables Reference

Runtime Configuration

Variable	Required	Default	Description
`NODE_ENV`	No	`development`	Runtime environment (`development`, `production`, `test`)
`ENVIRONMENT`	No	`development`	Application environment (`development`, `staging`, `production`)
`PORT`	No	`3001`	Port for local NestJS server (not used in Lambda)

NODE_ENV=development
ENVIRONMENT=development
PORT=3001

Database

Variable	Required	Default	Description
`DATABASE_URL`	Yes	-	PostgreSQL connection string

Local Development: Point to your local PostgreSQL instance.Production: The Lambda’s DATABASE_URL is constructed automatically by CloudFormation using Secrets Manager for the password.

DATABASE_URL=postgresql://postgres:yourpassword@localhost:5432/alliance_risk_dev

Critical for Lambda: Without DATABASE_URL, Prisma falls back to localhost and the Lambda will fail. The CloudFormation template automatically sets this using !Sub with Secrets Manager resolution.

AWS Cognito

Variable	Required	Default	Description
`COGNITO_USER_POOL_ID`	Yes	-	Cognito User Pool ID (e.g., `us-east-1_aBcDeF123`)
`COGNITO_CLIENT_ID`	Yes	-	Cognito App Client ID
`AWS_REGION`	Yes	`us-east-1`	AWS region for Cognito and other services

COGNITO_USER_POOL_ID=us-east-1_aBcDeF123
COGNITO_CLIENT_ID=1a2b3c4d5e6f7g8h9i0j1k2l3m
AWS_REGION=us-east-1

Get these values from the AWS Console → Cognito → User Pools after deploying infrastructure.

CORS Configuration

Variable	Required	Default	Description
`CORS_ORIGIN`	No	`http://localhost:3000`	Comma-separated allowed origins for CORS

CORS_ORIGIN=http://localhost:3000

S3 File Storage

Variable	Required	Default	Description
`S3_BUCKET_NAME`	Yes	-	S3 bucket name for file uploads

S3_BUCKET_NAME=alliance-risk-files-dev

The bucket is created by the CloudFormation stack. Reference the bucket name from the stack outputs.

Worker Lambda

Variable	Required	Default	Description
`WORKER_FUNCTION_NAME`	Yes	-	Worker Lambda function name for async job processing

WORKER_FUNCTION_NAME=alliance-risk-worker

The API Lambda invokes the Worker Lambda asynchronously for long-running Bedrock operations. The function name is set by CloudFormation.

Complete API .env Example

# Environment
NODE_ENV=development
ENVIRONMENT=development
PORT=3001

# Database (replace with your local or dev connection string)
DATABASE_URL=postgresql://postgres:your_password@localhost:5432/alliance_risk_dev

# AWS Cognito
COGNITO_USER_POOL_ID=us-east-1_aBcDeF123
COGNITO_CLIENT_ID=1a2b3c4d5e6f7g8h9i0j1k2l3m
AWS_REGION=us-east-1

# CORS (comma-separated for multiple origins)
CORS_ORIGIN=http://localhost:3000

# S3
S3_BUCKET_NAME=alliance-risk-files-dev

# Worker Lambda
WORKER_FUNCTION_NAME=alliance-risk-worker

Web Environment Variables

The Web package (packages/web/) uses Next.js and supports environment variables prefixed with NEXT_PUBLIC_ for client-side access.

Web Variables Reference

API Configuration

Variable	Required	Default	Description
`NEXT_PUBLIC_API_URL`	No	`http://localhost:3001`	Base URL for the API backend

NEXT_PUBLIC_API_URL=http://localhost:3001

Client-Side Access: Variables prefixed with NEXT_PUBLIC_ are embedded in the browser bundle. Do NOT use this prefix for sensitive credentials.

Complete Web .env Example

# API Backend URL
NEXT_PUBLIC_API_URL=http://localhost:3001

The Web package has minimal environment configuration since it’s a static export deployed to S3. Most configuration happens on the API side.

Lambda Environment Variables (Production)

In production, Lambda functions receive environment variables through CloudFormation. You don’t need to set these manually—they’re configured in the infrastructure stack.

API Lambda Environment

Environment:
  Variables:
    NODE_ENV: production
    ENVIRONMENT: !Ref Environment  # dev|staging|production
    DATABASE_URL: !Sub
      - "postgresql://${Username}:${Password}@${Host}:5432/alliance_risk"
      - Username: postgres
        Password: !Sub "{{resolve:secretsmanager:${DbSecret}:SecretString:password}}"
        Host: !GetAtt Database.Endpoint.Address
    COGNITO_USER_POOL_ID: !Ref UserPool
    COGNITO_CLIENT_ID: !Ref UserPoolClient
    AWS_REGION: !Ref AWS::Region
    CORS_ORIGIN: !Ref CorsOrigin
    S3_BUCKET_NAME: !Ref FileBucket
    WORKER_FUNCTION_NAME: !Ref WorkerLambda
    AWS_ACCOUNT_ID: !Ref AWS::AccountId

Worker Lambda Environment

Environment:
  Variables:
    NODE_ENV: production
    ENVIRONMENT: !Ref Environment
    DATABASE_URL: !Sub
      - "postgresql://${Username}:${Password}@${Host}:5432/alliance_risk"
      - Username: postgres
        Password: !Sub "{{resolve:secretsmanager:${DbSecret}:SecretString:password}}"
        Host: !GetAtt Database.Endpoint.Address
    AWS_ACCOUNT_ID: !Ref AWS::AccountId

DATABASE_URL is critical: Both Lambdas must have this environment variable. Without it, Prisma defaults to localhost and the Lambda will fail to connect to RDS.

Environment-Specific Configuration

Development

Local PostgreSQL database
API on http://localhost:3001
Web on http://localhost:3000
Mock AWS services or use dev AWS account

Staging

RDS PostgreSQL in private VPC
API Lambda behind API Gateway
Web static export on S3 + CloudFront
Separate Cognito User Pool
AWS Bedrock with dev model access

Production

Production RDS instance
High-performance Lambda configurations
Production Cognito User Pool
CloudFront with custom domain
Production Bedrock access

Security Best Practices

Never commit secrets to version control:

Add .env to .gitignore
Use .env.example files as templates (with placeholder values)
Rotate credentials regularly
Use AWS Secrets Manager for production credentials

What NOT to commit:

.env (actual environment variables)
Database passwords
AWS access keys
Cognito client secrets
API keys or tokens

What IS safe to commit:

.env.example (template with placeholder values)
CloudFormation templates (use !Sub and Secrets Manager)
Variable names and descriptions (this documentation)

Validation

Check API Configuration

Verify the API can connect to services:

# Start API server
pnpm dev:api

# Check health endpoint
curl http://localhost:3001/api/health

# Should return: {"status":"ok"}

Check Web Configuration

Verify the Web app can reach the API:

# Start both servers
pnpm dev

# Open browser console at http://localhost:3000
# Check Network tab for API calls to http://localhost:3001

Check Database Connection

Test Prisma connection:

cd packages/api
npx prisma db pull

# Should succeed without errors

Troubleshooting

”Prisma Client could not find your DATABASE_URL”

Cause: DATABASE_URL is not set in your .env file. Solution:

echo 'DATABASE_URL=postgresql://postgres:password@localhost:5432/alliance_risk_dev' >> packages/api/.env

“Cannot connect to Cognito”

Cause: Invalid COGNITO_USER_POOL_ID or COGNITO_CLIENT_ID. Solution: Get correct values from AWS Console → Cognito → User Pools.

”CORS error in browser”

Cause: CORS_ORIGIN doesn’t match the frontend URL. Solution: Update CORS_ORIGIN in packages/api/.env:

CORS_ORIGIN=http://localhost:3000

Lambda “Connection timeout” in production

Cause: Lambda can’t reach RDS due to missing DATABASE_URL or VPC configuration. Solution: Check CloudWatch logs and verify:

DATABASE_URL is set in Lambda environment
Lambda is in the same VPC as RDS
Security groups allow traffic on port 5432

Next Steps

Set up local development environment
Deploy infrastructure using CloudFormation
Configure AWS services (Cognito, RDS, Bedrock)
Deploy API and Web packages to AWS

Setup

AWS Infrastructure

Operations

API Environment Variables

Local Development (.env file)

API Variables Reference

Runtime Configuration

Database

AWS Cognito

CORS Configuration

S3 File Storage

Worker Lambda

Complete API .env Example

Web Environment Variables

Web Variables Reference

API Configuration

Complete Web .env Example

Lambda Environment Variables (Production)

API Lambda Environment

Worker Lambda Environment

Environment-Specific Configuration

Development

Staging

Production

Security Best Practices

What NOT to commit:

What IS safe to commit:

Validation

Check API Configuration

Check Web Configuration

Check Database Connection

Troubleshooting

”Prisma Client could not find your DATABASE_URL”

“Cannot connect to Cognito”

”CORS error in browser”

Lambda “Connection timeout” in production

Next Steps

Build docs developers (and LLMs) love

Setup

AWS Infrastructure

Operations

Documentation Index

​API Environment Variables

​Local Development (.env file)

​API Variables Reference

​Runtime Configuration

​Database

​AWS Cognito

​CORS Configuration

​S3 File Storage

​Worker Lambda

​Complete API .env Example

​Web Environment Variables

​Web Variables Reference

​API Configuration

​Complete Web .env Example

​Lambda Environment Variables (Production)

​API Lambda Environment

​Worker Lambda Environment

​Environment-Specific Configuration

​Development

​Staging

​Production

​Security Best Practices

​What NOT to commit:

​What IS safe to commit:

​Validation

​Check API Configuration

​Check Web Configuration

​Check Database Connection

​Troubleshooting

​”Prisma Client could not find your DATABASE_URL”

​“Cannot connect to Cognito”

​”CORS error in browser”

​Lambda “Connection timeout” in production

​Next Steps

Build docs developers (and LLMs) love

API Environment Variables

Local Development (.env file)

API Variables Reference

Runtime Configuration

Database

AWS Cognito

CORS Configuration

S3 File Storage

Worker Lambda

Complete API .env Example

Web Environment Variables

Web Variables Reference

API Configuration

Complete Web .env Example

Lambda Environment Variables (Production)

API Lambda Environment

Worker Lambda Environment

Environment-Specific Configuration

Development

Staging

Production

Security Best Practices

What NOT to commit:

What IS safe to commit:

Validation

Check API Configuration

Check Web Configuration

Check Database Connection

Troubleshooting

”Prisma Client could not find your DATABASE_URL”

“Cannot connect to Cognito”

”CORS error in browser”

Lambda “Connection timeout” in production

Next Steps