managarten/docs/ENVIRONMENT_VARIABLES.md

Environment Variables Guide

This document explains the centralized environment variable system for the Mana Core monorepo.

Quick Start

# After cloning the repo, install dependencies (auto-generates .env files)
pnpm install

# Or manually generate .env files
pnpm setup:env

That's it! All app-specific .env files are generated from .env.development.

How It Works

.env.development          # Central config (committed)
        │
        ▼
scripts/generate-env.mjs  # Transforms variables
        │
        ▼
apps/**/apps/**/.env      # Generated files (gitignored)

The generator reads .env.development and creates app-specific .env files with the correct prefixes for each platform:

Platform	Prefix	Example
Expo (mobile)	EXPO_PUBLIC_	EXPO_PUBLIC_SUPABASE_URL
SvelteKit (web)	PUBLIC_	PUBLIC_SUPABASE_URL
Hono/Bun (server)	None	DATABASE_URL

File Locations

Source File

• .env.development - Single source of truth, committed to git

Generated Files (gitignored)

• services/mana-auth/.env
• apps/chat/apps/server/.env
• apps/chat/apps/mobile/.env
• apps/chat/apps/web/.env
• apps/manacore/apps/mobile/.env
• apps/manacore/apps/web/.env
• apps/manadeck/apps/server/.env
• apps/manadeck/apps/web/.env
• apps/*/apps/server/.env (all apps with compute servers)
• apps/*/apps/web/.env (all web apps)
• apps/*/apps/mobile/.env (all mobile apps)

Variable Reference

Shared Variables

Variable	Description	Used By
MANA_CORE_AUTH_URL	Auth service URL	All apps
JWT_PRIVATE_KEY	JWT signing key	mana-core-auth
JWT_PUBLIC_KEY	JWT verification key	All backends
POSTGRES_USER	Database user	Docker, backends
POSTGRES_PASSWORD	Database password	Docker, backends
REDIS_HOST	Redis host	mana-core-auth
REDIS_PORT	Redis port	mana-core-auth
REDIS_PASSWORD	Redis password	mana-core-auth

Mana Core Auth Service

Variable	Description	Default
MANA_CORE_AUTH_PORT	Service port	3001
MANA_CORE_AUTH_DATABASE_URL	PostgreSQL connection string	-
JWT_ACCESS_TOKEN_EXPIRY	Access token TTL	15m
JWT_REFRESH_TOKEN_EXPIRY	Refresh token TTL	7d
JWT_ISSUER	JWT issuer claim	manacore
JWT_AUDIENCE	JWT audience claim	manacore
STRIPE_SECRET_KEY	Stripe secret key	-
STRIPE_PUBLISHABLE_KEY	Stripe publishable key	-
STRIPE_WEBHOOK_SECRET	Stripe webhook secret	-
CORS_ORIGINS	Allowed CORS origins	-
RATE_LIMIT_TTL	Rate limit window (seconds)	60
RATE_LIMIT_MAX	Max requests per window	100

Chat Project

Variable	Description	Default
CHAT_BACKEND_PORT	Backend service port	3002
CHAT_DATABASE_URL	PostgreSQL connection string	-
AZURE_OPENAI_ENDPOINT	Azure OpenAI endpoint URL	-
AZURE_OPENAI_API_KEY	Azure OpenAI API key	-
AZURE_OPENAI_API_VERSION	API version	2024-12-01-preview
CHAT_SUPABASE_URL	Supabase project URL	-
CHAT_SUPABASE_ANON_KEY	Supabase anonymous key	-

Manacore Project

Variable	Description
MANACORE_SUPABASE_URL	Supabase project URL
MANACORE_SUPABASE_ANON_KEY	Supabase anonymous key

Manadeck Project

Variable	Description	Default
MANADECK_BACKEND_PORT	Backend service port	3004
MANADECK_SUPABASE_URL	Supabase project URL	-
MANADECK_SUPABASE_ANON_KEY	Supabase anonymous key	-

Adding New Variables

Step 1: Add to .env.development

# In .env.development
MY_NEW_PROJECT_API_KEY=your-api-key
MY_NEW_PROJECT_URL=https://api.example.com

Step 2: Update the Generator Script

Edit scripts/generate-env.mjs and add your app config:

// In APP_CONFIGS array
{
  path: 'apps/my-project/apps/mobile/.env',
  vars: {
    // For Expo, add EXPO_PUBLIC_ prefix
    EXPO_PUBLIC_API_KEY: (env) => env.MY_NEW_PROJECT_API_KEY,
    EXPO_PUBLIC_API_URL: (env) => env.MY_NEW_PROJECT_URL,
  },
},
{
  path: 'apps/my-project/apps/web/.env',
  vars: {
    // For SvelteKit, add PUBLIC_ prefix
    PUBLIC_API_KEY: (env) => env.MY_NEW_PROJECT_API_KEY,
    PUBLIC_API_URL: (env) => env.MY_NEW_PROJECT_URL,
  },
},
{
  path: 'apps/my-project/apps/server/.env',
  vars: {
    // For Hono/Bun servers, no prefix needed
    API_KEY: (env) => env.MY_NEW_PROJECT_API_KEY,
    API_URL: (env) => env.MY_NEW_PROJECT_URL,
  },
},

Step 3: Regenerate

pnpm setup:env

Local Overrides

If you need to override variables locally without affecting others:

1. The generated .env files are gitignored
2. You can manually edit them after generation
3. Or create .env.local files (also gitignored) that some frameworks auto-load

Note: Running pnpm setup:env will overwrite your changes, so use .env.local for persistent overrides.

Docker Integration

The root .env.development is also used by Docker Compose:

# Start all services with shared env
pnpm docker:up:all

Docker services read from:

• Root .env.development for shared values
• Service-specific .env files for service-specific values

Troubleshooting

"Variable is undefined" Error

1. Check if the variable exists in .env.development
2. Run pnpm setup:env to regenerate
3. Restart your dev server (env changes require restart)

Generated File Has Wrong Value

1. Check the mapping in scripts/generate-env.mjs
2. Ensure the source variable name matches exactly
3. Run pnpm setup:env again

New App Not Getting Generated

1. Add app config to APP_CONFIGS in scripts/generate-env.mjs
2. Ensure the target directory exists
3. Run pnpm setup:env

Expo Not Picking Up Changes

Expo caches environment variables. Clear the cache:

cd apps/<project>/apps/mobile
npx expo start -c

Security Notes

• .env.development contains development-only values
• Never put production secrets in this file
• The JWT keys in .env.development are for local development only
• Use separate secrets management for production (1Password, AWS Secrets Manager, etc.)

Migration from Old System

If you have existing .env files with real values:

1. Copy important values to .env.development
2. Delete the old .env files
3. Run pnpm setup:env
4. Verify apps still work

The old .env.example files can remain as documentation.