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

3.9 KiB

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