Skip to content

environment.md

Latest commit

 

History

History
115 lines (91 loc) · 12.9 KB

environment.md

File metadata and controls

115 lines (91 loc) · 12.9 KB

Environment Variables

Pulse relies on a shared PostgreSQL database plus a collection of third-party services. The table below explains every environment variable referenced in the codebase, where it is used, and whether it is required. Start from .env.example and consult this document when promoting the project to production.

Global Configuration

Variable Required Default Used by Description
DATABASE_URL ✅ – All services PostgreSQL connection string (postgresql://user:pass@host:port/db).
OPENROUTER_API_KEY ⚠️* – Web, The Brain API key for OpenRouter hosted AI models. Required by the current the-brain worker.
NEARAI_API_KEY optional – Web Optional NEAR AI key for web-side model selection and future integrations.
DISCOURSE_BASE_URL ✅ when running Discourse listener https://gov.near.org Web, Discourse listener Base URL of the Discourse instance to mirror.
RUST_LOG optional info Rust services Sets tracing verbosity (trace, debug, info, warn, error).

⚠️* The current the-brain service requires OPENROUTER_API_KEY at startup.

Web Application (Next.js)

Variable Required Default Description
BETTER_AUTH_SECRET ✅ – Shared secret for Better Auth session signing. Use a 32+ byte random value.
BETTER_AUTH_URL ✅ http://localhost:3000 Origin used by Better Auth callbacks (must match deployed domain).
NEXT_PUBLIC_APP_URL ✅ http://localhost:3000 Publicly accessible base URL; exposed to client-side code.
DEV_AUTH_BYPASS optional (dev only) false When true, authentication is bypassed for local development. Disable in production.
GITHUB_CLIENT_ID ✅ (production) – GitHub OAuth app client ID for Better Auth.
GITHUB_CLIENT_SECRET ✅ (production) – GitHub OAuth app secret.
NEAR_EMAIL_DOMAIN optional – Restrict NEAR login to a specific email-like suffix (e.g. near.foundation).
NEAR_ALLOW_ANONYMOUS optional true Set to false to require verified NEAR accounts only.
NEAR_NETWORK optional mainnet NEAR network used for wallet validation (mainnet, testnet, etc.).
NEAR_RPC_URL optional derived from NEAR_NETWORK Override RPC endpoint for NEAR validation.
NEAR_EXPLORER_URL optional https://explorer.near.org/accounts Explorer base URL for profile deep-links.
NEXT_PUBLIC_NEAR_NETWORK optional mainnet Client-side hint for NEAR login UI.
FLAGS_SECRET ✅ – 32 byte secret for Vercel feature flags (base64url encoded).
RESEND_API_KEY optional – Enables transactional email via Resend.
EMAIL_FROM optional noreply@example.com Default "from" email address when Resend is configured.

Deployment Guards

These optional variables control the development auth bypass:

Variable Description
VERCEL_ENV When set to production, bypass is disabled automatically.
RAILWAY_ENVIRONMENT Disable bypass when value is production.
DEPLOYMENT_ENV / APP_ENV If either equals production, bypass is disabled.
IS_LOCAL / DOCKER_ENV Required for local production-like runs when NODE_ENV=production.

For local Docker or pnpm start style runs, set DEV_AUTH_BYPASS=true plus either IS_LOCAL=true or DOCKER_ENV=development. Public deployments should keep DEV_AUTH_BYPASS=false.

The Brain (AI Worker)

Variable Required Default Description
OPENROUTER_API_KEY ✅ – Required by the current worker startup path.
NEARAI_API_KEY optional – Reserved for alternative providers and web-side tooling.
RATING_CONCURRENCY optional 5 Maximum number of jobs processed in parallel.
POLL_INTERVAL_MS optional 5000 Interval between polling queue for new jobs (milliseconds).
MAX_RETRIES optional 3 Max retry attempts before a job is marked failed.
PROCESSING_TIMEOUT_MS optional 900000 Time before in-flight jobs are considered stuck (default 15 minutes).
HEALTH_PORT optional 3001 Port exposed by the health check server.
PORT optional falls back to HEALTH_PORT Alternative override for health server port (useful on platforms that set PORT).

Discourse Listener

Variable Required Default Description
DISCOURSE_BASE_URL ✅ – Base URL of the Discourse instance to sync (e.g. https://gov.near.org).
DATABASE_URL ✅ – Shared PostgreSQL database; see global section.

Telegram Listener

Variable Required Default Description
TELEGRAM_API_ID ✅ – Numeric API ID from https://my.telegram.org.
TELEGRAM_API_HASH ✅ – API hash paired with the Telegram API ID.
TELEGRAM_SESSION_FILE optional telegram_session.bin Persistent session file path (ensure the directory is writable).
TELEGRAM_SESSION_DATA optional – Base64-encoded session blob; takes precedence over the session file and is ideal for Railway or other ephemeral platforms.
TELEGRAM_CHANNELS ✅ – Comma-separated list of channel usernames or numeric IDs to ingest.
SYNC_BATCH_SIZE optional 100 Number of messages fetched per batch.
SYNC_INTERVAL_MINUTES optional 15 Interval between periodic backfill runs.
MAX_CONCURRENT_CHANNELS optional 5 Parallel channel sync limit.
MAX_RETRY_ATTEMPTS optional 3 Retry attempts for failed API calls.
RETRY_BASE_DELAY_SECONDS optional 60 Base delay for exponential backoff between retries.
MAX_MESSAGES_TO_SYNC optional – Hard cap on messages per channel per poll (omit for unlimited).
MAX_DB_CONNECTIONS optional 10 Maximum Postgres connections for the listener pool.
TELEGRAM_ALLOW_INTERACTIVE_LOGIN optional false When true, allows interactive CLI login if the session file is missing.

TELEGRAM_SESSION_DATA is checked before TELEGRAM_SESSION_FILE. For long-running Docker hosts, a mounted TELEGRAM_SESSION_FILE is usually simpler. For Railway or any platform without durable storage, TELEGRAM_SESSION_DATA is the safer default.

NEAR Balance Listener

Variable Required Default Description
FASTNEAR_API_URL optional https://api.fastnear.com Endpoint for FastNEAR API.
FASTNEAR_API_KEY optional – API key for higher rate limits (not required for public tier).
NEAR_BALANCE_POLL_INTERVAL_MINUTES optional 15 Polling cadence for balance snapshots.
NEAR_BALANCE_BATCH_SIZE optional 50 Number of accounts processed per poll.
NEAR_BALANCE_CONCURRENCY optional 10 Concurrent API requests to FastNEAR.

Front-End Defaults

The Next.js app exposes a few variables to client-side code; ensure they are safe to share publicly.

Variable Purpose
NEXT_PUBLIC_APP_URL Used to construct absolute links in the UI.
NEXT_PUBLIC_NEAR_NETWORK Configures the NEAR login widget (mainnet, testnet, etc.).

Tips

  • Keep secrets out of version control. Prefer .env for local development and managed secret stores (Railway/Vercel/Render/Heroku) in production.
  • Any time you change the database schema, re-run pnpm db:generate to refresh type definitions for both TypeScript and Rust.
  • DEV_AUTH_BYPASS should remain false in any environment that is exposed to the internet.