Environment Variables

Environment Variables

This document provides a complete reference for all environment variables required to run the Merq platform. Each component (merq-backend, merq-web, merq-mobile) has its own environment file.

Backend (merq-backend)

Create a .env file from env.example in the merq-backend root directory.

Application

Variable	Default Value	Required	Description
SERVER_PORT	8080	No	The port on which the Gin server will run.
APP_ENV	development	No	The application environment (development, staging, production).
ADMIN_BASE_URL	http://localhost:3000	No	The base URL of the web dashboard, used for generating links in emails.
APP_BASE_URL	http://localhost:3001	No	The base URL of the mobile app’s deep link schema.
JWT_SECRET		Yes	A secret key of at least 32 characters for signing JWT tokens.
JWT_EXPIRY_HOURS	24	No	The duration (in hours) for which an access token is valid.
JWT_REFRESH_EXPIRY_DAYS	30	No	The duration (in days) for which a refresh token is valid.
RUN_MIGRATION	false	No	Set to true to auto-run database migrations on startup. Used for first-deploy automation.
RUN_SEEDER	false	No	Set to true to auto-run the database seeder on startup. Requires SU_* and WS_* vars to be set.

Database & Cache

Variable	Default Value	Required	Description
DB_HOST	localhost	Yes	The hostname of the PostgreSQL database.
DB_PORT	5432	Yes	The port of the PostgreSQL database.
DB_USER	postgres	Yes	The username for the PostgreSQL database.
DB_PASSWORD		Yes	The password for the PostgreSQL database.
DB_NAME	merq_db	Yes	The name of the PostgreSQL database.
DB_SSLMODE	disable	No	The SSL mode for the database connection (disable, require, etc.).
DB_TIMEZONE	Asia/Jakarta	No	The timezone for the database connection.
REDIS_HOST	localhost	Yes	The hostname of the Redis server.
REDIS_PORT	6379	Yes	The port of the Redis server.
REDIS_PASSWORD		No	The password for the Redis server.
REDIS_DB	0	No	The Redis database number to use.

Rate Limiting

These variables override the default rate limit values. See Integrations & Rate Limiting for full details.

Variable	Default	Description
RATE_LIMIT_LOGIN_LIMIT	10	Max login/auth attempts per minute (IP-based).
RATE_LIMIT_AUTH_LIMIT	300	Max general authenticated requests per minute (user-based).
RATE_LIMIT_SEARCH_LIMIT	60	Max search requests (with keyword param) per minute (user-based).
RATE_LIMIT_EXPORT_LIMIT	5	Max export generate/download requests per minute (user-based).
RATE_LIMIT_REINDEX_LIMIT	1	Max reindex requests per 5-minute window (user-based).
RATE_LIMIT_REDIS_PREFIX	merq:ratelimit	Key prefix for rate limit counters (reserved for future Redis integration).

External Services

Variable	Default Value	Required	Description
TYPESENSE_HOST	localhost	No	The hostname of the Typesense search server.
TYPESENSE_PORT	8108	No	The port of the Typesense search server.
TYPESENSE_PROTOCOL	http	No	The protocol for Typesense (http or https).
TYPESENSE_API_KEY		No	The API key for Typesense.
FIREBASE_CREDENTIALS_FILE	./firebase/service-account.json	No	Path to the Firebase service account JSON for push notifications.
DO_SPACES_KEY		No	The access key for DigitalOcean Spaces (S3-compatible storage).
DO_SPACES_SECRET		No	The secret key for DigitalOcean Spaces.
DO_SPACES_BUCKET		No	The name of the bucket in DigitalOcean Spaces.
DO_SPACES_ENDPOINT	https://sgp1.digitaloceanspaces.com	No	The endpoint URL for the S3-compatible storage.
DO_SPACES_REGION	sgp1	No	The DigitalOcean Spaces region slug.

Email

Email uses a failover chain: Resend → Plunk → Mailersend. At least one provider must be configured for password reset to work.

Variable	Description
RESEND_API_KEY	API key for the Resend email service (primary).
RESEND_SENDER_EMAIL	Sender address for Resend.
PLUNK_API_KEY	API key for Plunk (first fallback).
PLUNK_SENDER_EMAIL	Sender address for Plunk.
MAILERSEND_API_KEY	API key for Mailersend (second fallback).
MAILERSEND_SENDER_EMAIL	Sender address for Mailersend.
MAIL_FROM	Generic fallback “from” address used if no provider-specific sender is set.

First-Time Setup

These variables are only needed for the initial seeder run (RUN_SEEDER=true). They seed the first super admin and workspace.

Variable	Description
SU_NAME	Full name of the initial super admin user.
SU_EMAIL	Email address of the initial super admin user.
SU_PASSWORD	Password for the initial super admin user.
SU_PHONE	Phone number for the initial super admin user.
WS_NAME	Name of the initial workspace.
WS_DESCRIPTION	Description of the initial workspace.
WS_SLUG	URL-safe slug for the initial workspace (e.g., default).

Web Dashboard (merq-web)

Create a .env.local file from .env.example in the merq-web root directory.

Variable	Default Value	Required	Description
VITE_API_BASE_URL	http://localhost:8080/api	Yes	The full base URL of the backend API.
VITE_GOOGLE_API_KEY		For Maps	Your Google Maps API key, required to render map components.
VITE_SECURE_LOCAL_STORAGE_HASH_KEY		Yes	A 32-character secret key used to encrypt sensitive items in browser storage.
VITE_SECURE_LOCAL_STORAGE_PREFIX	merq_	No	Key prefix used for secure local storage entries.
VITE_SECURE_LOCAL_STORAGE_DISABLED_KEYS		No	Comma-separated list of storage keys to exclude from encryption.
VITE_APP_ENV	development	No	The application environment (development, staging, production).
VITE_APP_NAME	Merq Admin	No	The application name displayed in the UI.

Mobile App (merq-mobile)

Create a .env.dev or .env.prod file from .env.example in the merq-mobile root directory. The active env file is selected at runtime via the ENVFILE environment variable (e.g., ENVFILE=.env.dev yarn android).

Variable	Default Value	Required	Description
API_BASE_URL	http://localhost:8080/api	Yes	The base URL of the backend API. For physical devices, use your computer’s local network IP (e.g., http://192.168.1.10:8080/api).
STORAGE_ENC_KEY		Yes	A 32-character secret key used to encrypt the local MMKV storage on the device.
GOOGLE_MAPS_API_KEY		For Maps	Your Google Maps API key, required for map features on Android.
APP_ENV	development	No	The application environment (development, staging, production).
APP_NAME	Merq Field Force	No	The application name.