Configuration Guide

Sejong Pulse uses environment variables across the frontend, backend, workers, and deployment layers. This page summarizes the main variables already referenced in the repository.

Frontend Variables

The frontend centralizes its public runtime settings in stitch/frontend/src/lib/config.ts.

Variable	Purpose
`NEXT_PUBLIC_API_BASE_URL`	Base URL for backend API requests
`NEXT_PUBLIC_SUPABASE_URL`	Supabase project URL
`NEXT_PUBLIC_SUPABASE_ANON_KEY`	Public Supabase client key
`NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME`	Cloudinary cloud identifier for client uploads
`NEXT_PUBLIC_SENDBIRD_APP_ID`	Sendbird application identifier
`NEXT_PUBLIC_ALGOLIA_APP_ID`	Algolia application identifier
`NEXT_PUBLIC_ALGOLIA_SEARCH_KEY`	Search-only Algolia key

Core Backend Variables

These are required or commonly used in stitch/backend/main.py.

Variable	Purpose
`SUPABASE_URL`	Supabase project URL
`SUPABASE_ANON_KEY`	Backend-side anon key for user-scoped actions
`SUPABASE_SERVICE_ROLE_KEY`	Service-role key for privileged backend operations
`CORS_ALLOW_ORIGINS`	Comma-separated allowed origins
`FRONTEND_APP_URL`	Canonical frontend URL used in callbacks and emails
`OPENAI_API_KEY` or `OPENROUTER_API_KEY`	AI provider key for advisor requests
`OPENAI_API_BASE_URL`	OpenAI-compatible base URL, defaulting to OpenRouter
`AI_HTTP_REFERER`	Referrer sent to the AI provider
`AI_APP_TITLE`	Display title sent to the AI provider
`SENTRY_DSN`	Error tracking configuration

Search, Media, and Messaging

Variable	Purpose
`ALGOLIA_APP_ID`	Algolia application identifier
`ALGOLIA_WRITE_API_KEY`	Algolia write key for indexing
`ALGOLIA_SEARCH_API_KEY`	Optional search-only key for backend search calls
`ALGOLIA_PULSES_INDEX`	Pulse index name, default `pulses`
`CLOUDINARY_CLOUD_NAME`	Cloudinary cloud name
`CLOUDINARY_API_KEY`	Cloudinary API key
`CLOUDINARY_API_SECRET`	Cloudinary API secret
`SENDBIRD_APP_ID`	Sendbird app identifier
`SENDBIRD_API_KEY`	Sendbird server API token
`SENDBIRD_API_URL`	Optional override for the Sendbird API base URL

Realtime and Recommendation Services

Variable	Purpose
`LIVEKIT_URL`	LiveKit websocket URL
`LIVEKIT_API_KEY`	LiveKit API key
`LIVEKIT_API_SECRET`	LiveKit API secret
`LIVEKIT_DEV_MODE`	Enables local LiveKit defaults when `true`
`REDIS_URL`	Redis connection string for cache and workers
`REDIS_KEY_PREFIX`	Namespace prefix for cache and job keys
`GORSE_ENDPOINT` or `GORSE_ADDRESS`	Gorse API endpoint
`GORSE_API_KEY`	Gorse server API key
`GORSE_DISCOVERY_CATEGORY`	Category name used for discovery recommendations
`GORSE_PULSE_CATEGORY`	Category name used for pulse recommendations
`GORSE_TIMEOUT_SECONDS`	Timeout for recommendation calls

Billing and Email

Variable	Purpose
`SENDGRID_API_KEY`	SendGrid API token
`SENDGRID_FROM_EMAIL`	Sender address for transactional email
`STRIPE_SECRET_KEY`	Backend secret for billing provider integration
`STRIPE_WEBHOOK_SECRET`	Webhook signature verification
`STRIPE_PRICE_ID`	Subscription price identifier
`TOSS_PAYMENTS_API_BASE_URL`	Toss billing API base URL
`TOSS_PAYMENTS_CLIENT_KEY`	Toss client key
`TOSS_PAYMENTS_SECRET_KEY`	Toss server secret
`TOSS_PAYMENTS_WEBHOOK_URL_SECRET`	Secret used for webhook validation
`BILLING_INTERNAL_JOB_SECRET`	Secret for internal renewal job calls
`BILLING_TIMEZONE`	Billing timezone, currently `Asia/Seoul` in deployment config

Worker and Queue Controls

Variable	Purpose
`BACKGROUND_JOBS_INLINE`	Run background jobs inline instead of durably
`BACKGROUND_JOB_MAX_WORKERS`	Max local background worker count
`JOB_QUEUE_PROCESSING_TIMEOUT_SECONDS`	Timeout for job processing
`JOB_QUEUE_MAX_ATTEMPTS`	Retry count for jobs
`RECOMMENDATION_OUTBOX_BATCH_SIZE`	Batch size for recommendation outbox processing
`RECOMMENDATION_OUTBOX_IDLE_SLEEP_SECONDS`	Idle sleep time for the recommendation worker

Authentication and Identity

Variable	Purpose
`SEJONG_AUTH_INTERNAL_EMAIL_DOMAIN`	Internal email domain used for Sejong-to-Supabase account bootstrap

Deployment Files

stitch/render.yaml documents the current backend, worker, and cron configuration.
stitch/frontend/netlify.toml documents frontend deployment behavior on Netlify.

Recommended Approach

Keep public variables in the frontend environment only when the browser truly needs them.
Keep provider secrets on the backend or deployment platform.
Start with the minimum Supabase and API variables, then layer in integrations one by one.
Treat recommendation, messaging, billing, and call features as optional until their credentials are configured.