Configuration - Backend

Getting Started to Backend configuration — env vars, Supabase, and services OpenQuok.

2 min read

Connect your agent today

Draft from chat, review in your calendar, and publish only what you approve.

Overview

The backend reads its runtime settings from environment variables, and you also configure your Supabase project in the Supabase Dashboard (database, authentication, API keys, and related project settings).

An example file with the most commonly used settings is checked in at backend/.env.development.example. Copy it to backend/.env.development.local under backend/ (the example header explains load order and how it relates to backend/.env). Use that local file for secrets and overrides you do not commit.

For production, follow the same naming convention: maintain backend/.env.production.local (or inject the same keys from your host’s secret store). In local development, keep NODE_ENV set to development; for deployment, use production.

NODE_ENV=development
FRONTEND_DOMAIN_URL=https://localhost:5173

Warning

FRONTEND_DOMAIN_URL must match the exact origin you use to open the web app, including the scheme (http vs https) and hostname (www vs apex). The backend uses it to build OAuth redirect/callback URLs (for example /integration/oauth/threads).

The web dev server in this repo uses HTTPS on https://localhost:5173; use that value unless you intentionally run the web app on plain HTTP.

Keep it aligned with the web app’s VITE_FRONTEND_DOMAIN_URL so links and OAuth redirects point to the same scheme and host. Third-party dashboards (Meta, Stripe, etc.) must list the same origin in every full redirect URL—swapping www only in Meta while the API still sends the apex host (or the reverse) produces “invalid redirect” style errors.

Common setup steps

Start with the example env file

Copy backend/.env.development.example to backend/.env.development.local and fill in values. Restart the backend after changes.

Configure Supabase in the dashboard

Create a Supabase project, then collect the URL + keys you need for the backend (API keys and JWT settings). Some features (like cron integration on Supabase Cloud) require enabling a dashboard integration before running migrations.

Add optional services as needed

Configure Redis (recommended for production), Sentry (optional), Google OAuth (optional), email (Resend in production), and storage (Cloudflare R2 or local disk) depending on what you enable in your environment variables.