Environment Variables

This project uses a hybrid configuration system powered by AWS SSM Parameter Store. It supports both build-time (static) and dynamic (runtime, cached) configuration loading, with seamless support for local development, ECS, and production environments.

Overview

• Build-time config: Loaded from SSM at build/startup and injected into environment.
• Dynamic config: Fetched from SSM at runtime (with a 10-minute in-memory cache). This allows for live updates of secrets and credentials without redeploying the app.
• Local-only config: Used only in local development and not required in production.

How It Works

1. scripts/inject-config.ts

• Purpose: Loads all required build-time config from SSM and merges it into .env.local, preserving any existing local overrides.
• When to use: Run this script before building or starting the app locally or in CI/CD.

Logic:

• Fetches all config from SSM.
• Asserts that all required build-time keys are present.
• Merges SSM values into .env.local (existing values in .env.local take precedence).
• Only build-time config is injected; dynamic config is always fetched at runtime.
• At build-time, the SSM values are injected into .env

2. src/lib/config.ts

• Purpose: Central config loader for all server-side code.

Key Functions:

• loadServerConfig(): Loads and caches all config from SSM (10-minute cache).
• getConfigValue(key): Fetches a single config value (case-insensitive) from the cache or SSM.
• injectToProcessEnv(keys): Injects selected config values into process.env for libraries that require env vars.

Dynamic Config Use:
Any value that may change at runtime (e.g., API keys, credentials) should be fetched using getConfigValue().

3. Build-Time vs. Dynamic Config

• Build-time config is static for the lifetime of the server process. Changing these values requires a rebuild/restart.
• Dynamic config can be updated in SSM and will be picked up automatically (after cache expiry) without a restart.
• Local-only config is not required in production and should not be stored in SSM.

Usage Examples

Accessing Build-Time Config

const baseUrl = process.env.NEXT_PUBLIC_BASE_URL;

Accessing Dynamic Config

import { getConfigValue } from "@/lib/config";

// Server-side only
const apiKey = await getConfigValue("AGENT_API_KEY");

Using AWS SDK with Dynamic Credentials

import { getS3Client } from "@/lib/utils/s3";

const s3 = await getS3Client();
// S3 client will use SSM credentials if present, otherwise ECS task role

Best Practices

• Never store secrets in the codebase or static .env files. Use SSM Parameter Store for all secrets and config.
• Use build-time config for values that must be available at build or in the browser.
• Use dynamic config for secrets and values that may change without a redeploy.
• Prefer IAM roles for AWS credentials in production (ECS, EC2). Only use static keys for local/dev or special cases.
• Document all config variables and their intended use.

Troubleshooting

• If a required config is missing, the app will fail fast with a clear error message.
• If you update a dynamic config value in SSM, it will be picked up automatically after the cache expires (10 minutes).
• For local development, ensure .env.local is up to date by running npx tsx scripts/inject-config.ts.

FAQ

Q: Can I update secrets in SSM without redeploying?
A: Yes! All dynamic config is fetched at runtime and will be refreshed after the cache expires.

Q: What happens if AWS credentials are not set in SSM?
A: The AWS SDK will use the default provider chain (e.g., ECS task role), which is the recommended approach for production.

Q: Are client-side variables safe?
A: Only variables prefixed with NEXT_PUBLIC_ are exposed to the browser. Never store secrets in these variables.

For further details, see the source code in scripts/inject-config.ts and src/lib/config.ts.

Configuration Variables Reference

FROM_EMAIL

FROM_EMAIL is a configuration parameter (typically set as an environment variable or in a config store) that specifies the default "from" email address used when sending transactional or notification emails from your application.

Format: A valid email address string, e.g., noreply@yourdomain.com.

Purpose: Used as the sender address for emails (such as welcome emails, password resets, etc.) when a custom or organization-specific "from" address is not provided.

Example Value: noreply@csiorbit.com

Usage: If an organization does not have a custom fromEmail set in its metadata, the application will fall back to using FROM_EMAIL as the sender address for outgoing emails. This ensures all emails have a valid and recognizable sender.

AWS_S3_BUCKET

AWS_S3_BUCKET is a configuration parameter (usually set as an environment variable or in a config store) that specifies the name of the Amazon S3 bucket used for storing uploaded files and assets.

Format: A valid S3 bucket name string, e.g., my-app-uploads-bucket.

Purpose: Determines the destination S3 bucket for file uploads, such as chat attachments, user assets, or other application files.

Usage: Used by the file upload API and S3 client logic to know where to store and retrieve files in AWS S3. If this value is missing or incorrect, uploads will fail.

USE_AGENT

Purpose: The USE_AGENT configuration parameter determines whether the application should use the external "Lead Agent" API for generating responses, or fall back to a local/dummy agent that generates placeholder (dummy) data.

Type: Boolean (string: "true" or "false"; case-insensitive)

How it works:

If USE_AGENT is set to "true" (or any case-insensitive variant), the app will:

• Send requests to the external agent API (using the configured AGENT_API_URL and AGENT_API_KEY).
• Expect real, production-quality responses from the agent.
• Omit dummy data instructions in the prompt.

If USE_AGENT is set to "false" (or not set), the app will:

• Use a local/dummy agent that generates placeholder data for UI components.
• Add instructions to the prompt to generate and use dummy data.

Typical usage:

Set to "true" in production or when you want to use the real agent service. Set to "false" (or leave unset) in development, testing, or demo environments where real agent responses are not needed.

Example:

Location: This parameter is typically set in your environment variables (e.g., .env file or deployment environment config).

Related parameters:

• AGENT_API_URL
• AGENT_API_KEY

AGENT_API_KEY

Purpose: The AGENT_API_KEY configuration parameter stores the API key required to authenticate requests to the external agent API endpoint.

Type: String (a secret API key value)

How it is used in this context:

In the invokeLeadAgent function, AGENT_API_KEY is retrieved and included as the value of the x-api-key HTTP header in requests to the agent API. This key is required by the external agent service to verify that the request is coming from an authorized client.

Typical usage:

Set to the API key provided by the external agent service in your environment variables (e.g., .env file or deployment environment config). Should be kept secret and never exposed in client-side code or logs.

Security note:

Treat this value as sensitive information. Rotate the key if it is ever exposed or compromised.

AGENT_API_URL

Purpose: The AGENT_API_URL configuration parameter specifies the base URL of the external agent API endpoint that the application communicates with to invoke the agent service.

Type: String (a valid HTTPS URL)

How it is used in this context:

In the invokeLeadAgent function, AGENT_API_URL is retrieved and used as the destination URL for the POST request to the agent API.

Typical usage:

Set to the URL provided by your agent service provider in your environment variables (e.g., .env file or deployment environment config). Allows you to switch between different agent API environments (e.g., development, staging, production) by changing the URL.

Notes:

Ensure the URL is correct and accessible from your backend environment. If not set, the application will use the default provided in the code.

EMAIL_API_KEY

Purpose: The EMAIL_API_KEY configuration parameter stores the API key required to authenticate requests to the transactional email service provider.

Type: String (a secret API key value)

How it is used in this context:

In the sendPasswordResetEmail function, EMAIL_API_KEY is retrieved and included in the payload sent to the email API endpoint. This key is required by the email service to verify that the request is coming from an authorized client and to allow sending transactional emails (such as password reset emails).

Typical usage:

Set to the API key provided by your email service provider in your environment variables (e.g., .env file or deployment environment config). Should be kept secret and never exposed in client-side code or logs.

Security note:

Treat this value as sensitive information. Rotate the key if it is ever exposed or compromised.

EMAIL_API_URL

Purpose: The EMAIL_API_URL configuration parameter specifies the base URL of the transactional email API endpoint used to send emails (such as password reset emails).

Type: String (a valid HTTPS URL)

How it is used in this context:

In the sendPasswordResetEmail function, EMAIL_API_URL is retrieved and used as the destination URL for the POST request to the email service.

Typical usage:

Set to the URL provided by your email service provider in your environment variables (e.g., .env file or deployment environment config). Allows you to switch between different email API environments (e.g., development, staging, production) by changing the URL.

Notes:

Ensure the URL is correct and accessible from your backend environment. If not set, the application will use the default provided in the code.