Environment variables

Every setting in the .env file, what it does and its default.

Settings that belong to the server (secrets, keys, addresses) live in .env. Everything the store owner changes day to day (store name, shipping, VAT, payment switches, monthly goal) lives in Dashboard > Settings and is stored in the database. Restart the server after changing .env.

Required

Variable Example What it does
DATABASE_URL file:./souq.db Database connection. A SQLite file next to prisma/schema.prisma by default; a postgresql:// URL for PostgreSQL (Requirements).
SITE_URL https://shop.example.om Public address without a trailing slash. Used for Thawani return links, the sitemap, canonical links and Product structured data.
AUTH_SECRET 64 random hex characters Signs the dashboard and shopper session cookies. At least 16 characters; use 32+ in production. Changing it signs everyone out.

First owner

Variable Default What it does
OWNER_EMAIL owner@souq.test Email of the owner account created by npm run db:seed when there is no dashboard account yet.
OWNER_PASSWORD souq-demo-2026 Its password. Read only at that moment: later changes have no effect.

Demo helpers (never on a real store)

Variable Default What it does
DEMO_HINT 0 1 shows the owner email and password on the dashboard sign-in page.
SEED_DEMO_SHOPPER 0 1 makes the seed create a shopper account with two orders and a wishlist.
DEMO_SHOPPER_EMAIL shopper@souq.test That shopper's email.
DEMO_SHOPPER_PASSWORD souq-shopper-2026 That shopper's password.

Time

Variable Default What it does
STORE_TIMEZONE Asia/Muscat Time zone for "today", the months on the overview, coupon end dates and dates shown in the store.

Card payments (Thawani)

Variable Default What it does
THAWANI_MODE uat uat uses Thawani's test environment, live takes real payments.
THAWANI_SECRET_KEY empty Secret key from the Thawani merchant portal. Server only.
THAWANI_PUBLISHABLE_KEY empty Publishable key, used in the payment page link.

Card payment is offered only when both keys are set, the switch in Settings is on and the currency is OMR. Details in Payments.

AI (optional)

Variable Default What it does
AI_BASE_URL empty Base URL of any OpenAI-compatible API, for example https://api.openai.com/v1, https://openrouter.ai/api/v1 or a local Ollama http://localhost:11434/v1. Empty switches the AI features off.
AI_API_KEY empty Sent as Authorization: Bearer .... Leave empty for a local model without a key.
AI_MODEL gpt-4o-mini Model name as your provider spells it.

See AI features.

Settings in the dashboard, not in .env

Store names and taglines in both languages, the announcement bar, contact details, currency and decimals, VAT %, low-stock level, monthly sales goal, shipping methods with their governorates and free-delivery thresholds, cash on delivery and card switches, and "taking orders". The owner (or any role given the Settings permission) changes them in Dashboard > Settings.