mirror of
https://github.com/Memo-2023/mana-monorepo.git
synced 2026-05-20 15:49:23 +02:00
📝 docs: add Astro Starlight public documentation site
Add comprehensive documentation site using Astro Starlight with: - Getting Started guides (introduction, quick-start, project structure) - Development docs (local dev, env vars, docker, migrations, testing) - Architecture docs (overview, auth, backend, web, mobile, storage, search) - Guidelines (code style, error handling, database, design/UX) - Deployment docs (overview, Cloudflare Pages, Mac Mini, self-hosting) - Project pages (overview, chat) - API reference structure Features: - Dark mode support - Full-text search (Pagefind) - Tailwind CSS styling - Cloudflare Pages deployment ready - Edit on GitHub links
This commit is contained in:
Till-JS
parent
dff153ca1e
commit
4b322f59b1
38 changed files with 7497 additions and 234 deletions
185
apps/docs/src/content/docs/development/environment-variables.mdx
Normal file
185
apps/docs/src/content/docs/development/environment-variables.mdx
Normal file
|
|
@ -0,0 +1,185 @@
|
|||
---
|
||||
title: Environment Variables
|
||||
description: Centralized environment variable management in the Manacore monorepo.
|
||||
---
|
||||
|
||||
import { Tabs, TabItem, Aside, Steps } from '@astrojs/starlight/components';
|
||||
|
||||
# Environment Variables
|
||||
|
||||
Manacore 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_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 |
|
||||
|
||||
### Mana Core Auth Service
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `MANA_CORE_AUTH_PORT` | Service port | `3001` |
|
||||
| `MANA_CORE_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 | `manacore` |
|
||||
| `JWT_AUDIENCE` | JWT audience claim | `manacore` |
|
||||
| `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>
|
||||
Loading…
Add table
Add a link
Reference in a new issue