Configure Environment Variables

🛠️ Guide: Environment Configuration (.env)

The API server uses a .env file to manage environment-specific configuration, such as database connection strings, API keys, and feature toggles. This approach keeps sensitive data out of your source code.

Creating Your .env File

First, copy the example file to create your local configuration file. Run this command from the project root:

cp .env.example .env

Open the new .env file and fill in the values as described below.

1. Core Application Configuration (Required)

These variables are essential for the server to start and function correctly.

Variable	Description	Example / Default
DATABASE_URL	Required. The full connection string for your MongoDB instance.	mongodb://localhost:27017/my_db
JWT_SECRET_KEY	Required. A cryptographically secure random string used to sign JSON Web Tokens. Do not share this.	your-super-secret-key-at-least-64-chars
CORS_ALLOWED_ORIGIN	Required for Production. The URL of your web client (dashboard) allowed to make API requests.	https://dashboard.yourdomain.com
OVERRIDE_ADMIN_EMAIL	Optional. Sets the single administrator account on startup. If set, this user is guaranteed to be the admin.	admin@example.com

2. External Provider Credentials

Define your API keys and secrets here. These are referenced by various features like Analytics, Push Notifications, and Email.

Firebase / Google Cloud

Used for: Push Notifications (FCM), Google Analytics 4, Google Play Validation.

Variable	Description
FIREBASE_PROJECT_ID	The Project ID from your Firebase console.
FIREBASE_CLIENT_EMAIL	The client_email field from your Firebase Service Account JSON key.
FIREBASE_PRIVATE_KEY	The private_key field from your Firebase Service Account JSON key.

OneSignal

Used for: Push Notifications, Email Delivery.

Variable	Description
ONESIGNAL_APP_ID	The App ID for your OneSignal application.
ONESIGNAL_REST_API_KEY	The REST API Key for your OneSignal application.

SendGrid

Used for: Email Delivery.

Variable	Description
SENDGRID_API_KEY	Your SendGrid API Key.
SENDGRID_API_URL	(Optional) Base URL for the API. Defaults to https://api.sendgrid.com.

Mixpanel

Used for: Analytics.

Variable	Description
MIXPANEL_PROJECT_ID	Your Mixpanel Project ID.
MIXPANEL_SERVICE_ACCOUNT_USERNAME	The username for your Mixpanel Service Account.
MIXPANEL_SERVICE_ACCOUNT_SECRET	The secret for your Mixpanel Service Account.

3. Feature Configuration

Email Service (Static)

Select which provider to use for sending emails (e.g., OTPs).

Variable	Description
EMAIL_PROVIDER	Required. Choose one: sendgrid, onesignal, or logging (for local dev).
DEFAULT_SENDER_EMAIL	Required. The "From" address. Must be verified with your provider.
OTP_TEMPLATE_ID	Required. The ID of the email template used for OTPs.

Analytics

Configure the connection to your analytics provider.

Variable	Description
GOOGLE_ANALYTICS_PROPERTY_ID	The Property ID for your Google Analytics 4 property. Requires Firebase credentials to be set.

4. Rate Limiting & Security (Optional)

Fine-tune API security settings. Defaults are provided if these are not set.

Variable	Default	Description
RATE_LIMIT_REQUEST_CODE_LIMIT	3	Max sign-in attempts per window. Keep low to prevent abuse.
RATE_LIMIT_REQUEST_CODE_WINDOW_HOURS	24	Time window for sign-in limits (in hours).
RATE_LIMIT_DATA_API_LIMIT	1000	Max general API requests per window.
RATE_LIMIT_DATA_API_WINDOW_MINUTES	60	Time window for general API limits (in minutes).
JWT_EXPIRY_HOURS	720	Duration (in hours) a user session remains valid (30 days).