Configuration Reference
The most important environment variables and config groups that control MARCUS behavior.
This page highlights the settings that most directly change runtime behavior in MARCUS. It is not an exhaustive dump of every environment variable in the repository. Instead, it explains the configuration groups that operators and developers most often need to understand.
The canonical day-to-day sources of truth remain:
backend/.env.templatefrontend/.env.example- the centralized backend and frontend config modules
Runtime Environment
These variables decide what environment the app believes it is running in and which public URLs it should use.
| Variable | Meaning | Common values |
|---|---|---|
ENVIRONMENT | Main runtime environment selector used by backend settings resolution | local, staging, preview, production |
NEXT_PUBLIC_SITE_URL | Public frontend base URL used by the browser-facing app | localhost or deployed frontend URL |
NEXT_PUBLIC_API_BASE | Browser API base override when the frontend needs a different backend origin | local or deployed backend URL |
Use these carefully. A bad environment or base-URL setting can make a working app look broken simply because it is talking to the wrong deployment.
Retrieval, Generation, And Chat
These variables most directly affect how MARCUS answers questions.
| Variable | Meaning |
|---|---|
OPENAI_API_KEY | Required when OpenAI-backed generation or embeddings are active |
QUERY_SUGGESTIONS_ENABLED | Enables suggestion-generation behavior after answers |
NEXT_PUBLIC_API_STREAM_PATH | Frontend-visible streaming path, usually /api/query/stream |
NEXT_PUBLIC_API_COMPLETIONS_PATH | Frontend-visible non-stream chat path |
There are also deeper backend retrieval and prompt settings in the backend config surface. Those control things such as ranking, retrieval thresholds, or model behavior, but they should remain centralized rather than scattered through the codebase.
Database And Persistence
| Group or variable | What it controls |
|---|---|
DATABASE_URL and related database settings | PostgreSQL connectivity, schema-backed persistence, and backend data access |
| Migration and setup config | How schema changes are applied and validated |
If the database configuration is wrong, MARCUS may still boot partially but fail on any workflow that requires stored projects, sessions, sources, or analytics.
Queueing And Background Work
| Group or variable | What it controls |
|---|---|
REDIS_URL | Background job queue behavior for ingestion and other async work |
Operationally, this matters because MARCUS can fall back to inline or threaded behavior when Redis is absent, but the performance and concurrency characteristics differ. If uploads or enrichment feel unusually slow, queue configuration is one of the first things to inspect.
Storage
| Group or variable | What it controls |
|---|---|
STORAGE_S3_BUCKET, STORAGE_S3_ENDPOINT_URL, STORAGE_S3_REGION, and related storage vars | File persistence, uploaded source storage, and retrieval of stored assets |
Storage configuration determines whether uploaded files can be persisted and later re-read reliably. A source ingestion failure can be caused by storage misconfiguration even if the UI upload step itself appears to work.
Authentication And Session Security
| Variable or group | Meaning |
|---|---|
| Cookie-related settings | Control session cookie names, scope, and security behavior |
| CSRF-related settings | Control CSRF bootstrap and request protection behavior |
ENABLE_GOOGLE_SSO | Enables Google SSO surfaces and backend validation |
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET | Google OAuth credentials |
MICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET | Microsoft OAuth credentials |
OAUTH_VALIDATE_STRICT | Tightens OAuth validation behavior |
These values matter because MARCUS uses cookie-based auth and CSRF protection rather than simple bearer-token browser flows.
Billing
| Variable | Meaning |
|---|---|
STRIPE_SECRET_KEY | Canonical Stripe secret used when billing is enabled |
STRIPE_PUBLISHABLE_KEY | Frontend billing integration key |
STRIPE_WEBHOOK_SECRET | Stripe webhook verification secret |
NEXT_PUBLIC_BILLING_ENABLED | Frontend billing surface toggle |
Billing settings do not only affect payment pages. They can also change which plan or billing-related UI elements are visible in the app.
Frontend Feature Flags
These variables affect which UI surfaces appear to the user.
| Variable | Meaning |
|---|---|
NEXT_PUBLIC_ENABLE_FEEDBACK | Enables feedback controls |
NEXT_PUBLIC_ENABLE_SHAREPOINT | Enables SharePoint provider UI |
NEXT_PUBLIC_DISABLE_GOOGLE_DRIVE | Hides Google Drive integration UI when true |
NEXT_PUBLIC_DISABLE_ONEDRIVE | Hides OneDrive integration UI when true |
NEXT_PUBLIC_DISABLE_DROPBOX | Hides Dropbox integration UI when true |
NEXT_PUBLIC_SHOW_DEV_TOOLS | Shows developer overlays or developer-oriented surfaces |
NEXT_PUBLIC_DEBUG_API | Enables verbose frontend API logging |
NEXT_PUBLIC_DEBUG_RETRIEVAL | Enables retrieval-oriented debugging surfaces |
Feature flags are often the explanation when one environment shows a UI surface that another environment does not.
Environment Groups To Keep In Mind
For practical operations, it helps to think in groups rather than isolated variables:
- Runtime identity and URLs
- Authentication and security
- Database and storage
- Queueing and background jobs
- Retrieval and generation
- Billing and external integrations
- Frontend feature flags and debugging
When debugging, ask which group the symptom belongs to. That narrows the investigation quickly.
Safe Configuration Practices
- Treat
backend/.env.templateandfrontend/.env.exampleas the first stop for configuration discovery. - Keep environment reads centralized in the repo's config modules.
- Do not scatter new
os.getenv()orprocess.envreads around the codebase. - When adding a new flag, document it in the template file and the docs at the same time.
- Prefer environment-specific templates and deployment-managed secrets over hardcoded values.
A Practical Warning
Many bugs that look like retrieval bugs, login bugs, or broken uploads are actually configuration bugs. In MARCUS, environment correctness is part of product correctness, not just deployment housekeeping.