managarten/apps/docs/src/content/docs/development/environment-variables.mdx

---
title: Environment Variables
description: Centralized environment variable management in the Mana monorepo.
---

import { Tabs, TabItem, Aside, Steps } from '@astrojs/starlight/components';

# Environment Variables

Mana uses a centralized environment variable system. All development variables are managed from a single file.

## Quick Start

```bash
# After cloning, 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` |
| NestJS (backend) | None | `SUPABASE_URL` |

## File Locations

### Source File
- **`.env.development`** - Single source of truth, committed to git

### Generated Files (gitignored)
- `services/mana-core-auth/.env`
- `apps/chat/apps/backend/.env`
- `apps/chat/apps/mobile/.env`
- `apps/chat/apps/web/.env`
- And more...

## Variable Reference

### Shared Variables

| Variable | Description | Used By |
|----------|-------------|---------|
| `MANA_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 |

### Mana Core Auth Service

| Variable | Description | Default |
|----------|-------------|---------|
| `MANA_AUTH_PORT` | Service port | `3001` |
| `MANA_AUTH_DATABASE_URL` | PostgreSQL connection | - |
| `JWT_ACCESS_TOKEN_EXPIRY` | Access token TTL | `15m` |
| `JWT_REFRESH_TOKEN_EXPIRY` | Refresh token TTL | `7d` |
| `JWT_ISSUER` | JWT issuer claim | `mana` |
| `JWT_AUDIENCE` | JWT audience claim | `mana` |
| `STRIPE_SECRET_KEY` | Stripe secret key | - |
| `CREDITS_SIGNUP_BONUS` | Credits on signup | `150` |
| `CREDITS_DAILY_FREE` | Daily free credits | `5` |

### Project-Specific Variables

<Tabs>
  <TabItem label="Chat">
    | Variable | Description |
    |----------|-------------|
    | `CHAT_BACKEND_PORT` | Backend port (3002) |
    | `CHAT_DATABASE_URL` | PostgreSQL connection |
    | `AZURE_OPENAI_ENDPOINT` | Azure OpenAI endpoint |
    | `AZURE_OPENAI_API_KEY` | Azure OpenAI key |
  </TabItem>
  <TabItem label="Picture">
    | Variable | Description |
    |----------|-------------|
    | `PICTURE_BACKEND_PORT` | Backend port (3006) |
    | `REPLICATE_API_KEY` | Replicate AI key |
  </TabItem>
  <TabItem label="Zitare">
    | Variable | Description |
    |----------|-------------|
    | `ZITARE_BACKEND_PORT` | Backend port (3007) |
    | `ZITARE_DATABASE_URL` | PostgreSQL connection |
  </TabItem>
</Tabs>

## Adding New Variables

<Steps>
1. **Add to `.env.development`**

   ```bash
   MY_NEW_PROJECT_API_KEY=your-api-key
   MY_NEW_PROJECT_URL=https://api.example.com
   ```

2. **Update the Generator Script**

   Edit `scripts/generate-env.mjs`:

   ```javascript
   {
     path: 'apps/my-project/apps/backend/.env',
     vars: {
       API_KEY: (env) => env.MY_NEW_PROJECT_API_KEY,
       API_URL: (env) => env.MY_NEW_PROJECT_URL,
     },
   },
   ```

3. **Regenerate**

   ```bash
   pnpm setup:env
   ```
</Steps>

## Local Overrides

If you need to override variables locally:

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

<Aside type="caution">
Running `pnpm setup:env` will overwrite your changes in `.env` files. Use `.env.local` for persistent overrides.
</Aside>

## Docker Integration

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

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

## 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)

### Expo Not Picking Up Changes

Expo caches environment variables. Clear the cache:

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

## Security Notes

<Aside type="danger">
- `.env.development` contains **development-only** values
- Never put production secrets in this file
- The JWT keys are for local development only
- Use separate secrets management for production
</Aside>