This repository has been archived on 2026-11-17. You can view files and clone it, but cannot push or open issues or pull requests.
gitgram-ai/docs/environment-matrix.md
2026-06-22 17:45:56 +03:00

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