173 lines
3.9 KiB
Markdown
173 lines
3.9 KiB
Markdown
# Environment Matrix
|
|
|
|
Last updated: 2026-05-09
|
|
|
|
This is the canonical launch-time environment contract for the manual single-host deployment path.
|
|
|
|
Rules:
|
|
|
|
- Runtime env files live at repo root: `.env.gitgram`, `.env.gitgram-web`, `.env.aitm-api`, optional `.env.aitm-website`.
|
|
- Service-local `.env.example` files remain the code-level reference for development.
|
|
- `scripts/validate-prod-secrets.sh` accepts both unprefixed runtime names and `GITGRAM_*` / `AITM_*` aliases for CI-style validation.
|
|
|
|
## Gitgram Backend
|
|
|
|
Required before first launch:
|
|
|
|
- `DATABASE_URL`
|
|
- `REDIS_URL`
|
|
- `JWT_SECRET`
|
|
- `JWT_REFRESH_SECRET`
|
|
- `FRONTEND_URL`
|
|
- `CORS_ORIGIN`
|
|
- `GITHUB_CLIENT_ID`
|
|
- `GITHUB_CLIENT_SECRET`
|
|
- `POLAR_ACCESS_TOKEN`
|
|
- `POLAR_WEBHOOK_SECRET`
|
|
- `POLAR_PREMIUM_PRODUCT_ID`
|
|
- `POLAR_CREATOR_PRODUCT_ID`
|
|
- `POLAR_MODE`
|
|
- `RESEND_API_KEY`
|
|
- `SENTRY_DSN`
|
|
- `STORAGE_TYPE`
|
|
|
|
Conditional requirements:
|
|
|
|
- `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_S3_BUCKET`, `AWS_REGION` when `STORAGE_TYPE=s3`
|
|
|
|
Optional after launch:
|
|
|
|
- `GOOGLE_CLIENT_ID`
|
|
- `GOOGLE_CLIENT_SECRET`
|
|
- `GITHUB_WEBHOOK_SECRET`
|
|
- `GITHUB_TOKEN`
|
|
- `CDN_URL`
|
|
- `AITM_API_URL`
|
|
- `AITM_ENCRYPTION_SECRET`
|
|
- analytics and feature-flag keys
|
|
|
|
Code reference:
|
|
|
|
- `gitgram/backend/ENV_MATRIX.md`
|
|
- `gitgram/backend/.env.example`
|
|
- `gitgram/backend/src/config/env-contract.ts`
|
|
|
|
## Gitgram Web
|
|
|
|
Required before first launch:
|
|
|
|
- `NEXT_PUBLIC_API_URL`
|
|
- `NEXT_PUBLIC_WS_URL` or legacy `NEXT_PUBLIC_SOCKET_URL`
|
|
- `NEXT_PUBLIC_GITHUB_CLIENT_ID`
|
|
|
|
Optional after launch:
|
|
|
|
- `NEXT_PUBLIC_GOOGLE_CLIENT_ID`
|
|
- `NEXT_PUBLIC_AITM_API_URL`
|
|
- `NEXT_PUBLIC_SENTRY_DSN`
|
|
- `NEXT_PUBLIC_GA_ID`
|
|
- `NEXT_PUBLIC_MAPBOX_TOKEN`
|
|
|
|
Operational note:
|
|
|
|
- `NEXT_PUBLIC_*` values are build-time inputs. Rebuild the web app whenever they change.
|
|
|
|
Code reference:
|
|
|
|
- `gitgram/web/.env.example`
|
|
- `gitgram/web/next.config.js`
|
|
|
|
## AITM API
|
|
|
|
Required before first launch:
|
|
|
|
- `DATABASE_URL`
|
|
- `INTERNAL_SECRET`
|
|
- `CORS_ORIGIN`
|
|
- `WEBSITE_URL`
|
|
- `POLAR_ACCESS_TOKEN`
|
|
- `POLAR_WEBHOOK_SECRET`
|
|
- `POLAR_PRO_PRODUCT_ID`
|
|
- `POLAR_TEAM_PRODUCT_ID`
|
|
- `RESEND_API_KEY`
|
|
- `SENTRY_DSN`
|
|
|
|
Optional after launch:
|
|
|
|
- `CLERK_WEBHOOK_SECRET`
|
|
- `REDIS_URL`
|
|
- `OPENAI_API_KEY`
|
|
- `ANTHROPIC_API_KEY`
|
|
- `VOYAGE_API_KEY`
|
|
- `BRAVE_SEARCH_API_KEY`
|
|
- `SERPAPI_KEY`
|
|
- `SERPER_API_KEY`
|
|
- `FIRECRAWL_API_KEY`
|
|
- `KB_S3_BUCKET`
|
|
- `AWS_ACCESS_KEY_ID`
|
|
- `AWS_SECRET_ACCESS_KEY`
|
|
- worker toggles and cron expressions
|
|
|
|
Operational notes:
|
|
|
|
- `DATABASE_URL` must be valid before the API starts in `staging` or `production`.
|
|
- Without LLM/search keys, AI-heavy routes degrade gracefully instead of blocking startup.
|
|
- Worker env vars are only required if you enable the managed scheduler on launch day.
|
|
|
|
Code reference:
|
|
|
|
- `aitimemachine/api-server/.env.example`
|
|
- `aitimemachine/api-server/src/lib/validateEnv.ts`
|
|
- `aitimemachine/api-server/src/config/env-validation.ts`
|
|
|
|
## AITM npm Publish / Release Flow
|
|
|
|
Manual publish requires:
|
|
|
|
- authenticated npm session via `npm login` or `npm whoami`
|
|
|
|
Optional CI automation:
|
|
|
|
- GitHub secret `NPM_TOKEN`
|
|
|
|
Operational notes:
|
|
|
|
- The current CI release job publishes `@gitgram/timemachine`.
|
|
- `@gitgram/timemachine-mcp` still requires manual publish.
|
|
|
|
## Optional Self-Hosted AITM Website
|
|
|
|
Only required if you decide to run `aitimemachine/website` on the launch host.
|
|
|
|
Required for self-host:
|
|
|
|
- `NEXT_PUBLIC_API_URL`
|
|
- `API_URL`
|
|
- `INTERNAL_SECRET`
|
|
- `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`
|
|
- `CLERK_SECRET_KEY`
|
|
- `NEXT_PUBLIC_APP_URL`
|
|
- `POLAR_ACCESS_TOKEN`
|
|
- `NEXT_PUBLIC_POLAR_PRO_PRODUCT_ID`
|
|
- `NEXT_PUBLIC_POLAR_TEAM_PRODUCT_ID`
|
|
|
|
Code reference:
|
|
|
|
- `.env.aitm-website.example`
|
|
- `aitimemachine/website/.env.example`
|
|
|
|
## Validation Commands
|
|
|
|
```bash
|
|
bash scripts/validate-prod-secrets.sh staging
|
|
bash scripts/validate-prod-secrets.sh production
|
|
```
|
|
|
|
These checks:
|
|
|
|
- validate the launch-critical variable set
|
|
- support both prefixed and unprefixed naming
|
|
- auto-load the root `.env.*` files when present
|
|
- fail on placeholder values
|
|
- enforce `POLAR_MODE=production` for a production Gitgram launch
|