Environment variables

Where the settings live

Create each file from the .env.example next to it, which documents every variable: cp .env.example .env. The examples work as they are for a local run.

Where the settings live

One file, storefront/.env, read when the storefront is built. Every value in it is public, so it never holds a secret. Leave it out to run on the sample store; create it from .env.example when you connect an API: cp .env.example .env.

Where the settings live

One file, admin-dashboard/.env, read when the dashboard is built. Every value in it is public, so it never holds a secret. Leave it out to run on the sample store; create it from .env.example when you connect an API: cp .env.example .env.

Where the settings live

One file, back-end/.env, read by the API with yarn dev, and by a container when you pass it with --env-file .env. It holds secrets: never commit it. Create it from .env.example, which documents every variable and works as it is for a local run: cp .env.example .env.

API essentials

The API checks JWT_SECRET and CORS_ORIGIN before it starts. If one is missing or unusable, it stops with one line saying what to fix.

Generate your own JWT_SECRET with:

node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"

Any credential below still holding its exact .env.example value counts as not set, so the feature it belongs to reports itself off instead of failing on its first call.

Use MySQL instead of SQLite

Create an empty database, then set the driver and the connection in back-end/.env:

DB_TYPE=mysql
DB_HOST=your-mysql-host
DB_PORT=3306
DB_USERNAME=your-mysql-username
DB_PASSWORD=your-mysql-password
DB_DATABASE=your-database-name

Then run yarn seed for the demo store, or yarn db:sync for the tables with no data. The running API only creates and updates the tables itself when NODE_ENV=development, so with NODE_ENV=production one of those commands runs before the first start (yarn db:sync:prod or yarn seed:prod after yarn build).

Storefront and admin dashboard

Every NEXT_PUBLIC_* value is compiled into the JavaScript the browser loads, and anyone who opens the page can read it. Never put a secret in these files, and rebuild after changing one.

The storefront's marketing tags are NEXT_PUBLIC_* values too.

• Analytics and tracking pixels

Docker Compose options

Nothing has to be set for a local run. To change something, put it in a .env file next to docker-compose.yml and run docker compose up --build again: the frontends compile these values in.

The API container also reads back-end/.env when it exists, so payments, media and AI keys are set in one place for both yarn dev and Docker. The compose file wins for the few values that differ inside a container: the database path, the port, NODE_ENV=production, CORS_ORIGIN and FRONTEND_URL. The data lives in the ecommerce-data volume.

Media storage

Product photos, category images, avatars, chat attachments, the AI studio's results and the fitting room's photos are uploaded to a Cloudflare R2 bucket, or any S3-compatible one. Set the five variables in back-end/.env and give both frontends the bucket's public host through NEXT_PUBLIC_MEDIA_HOSTNAME (with Docker Compose, MEDIA_HOSTNAME).

R2_ACCESS_KEY_ID=
R2_SECRET_ACCESS_KEY=
R2_ENDPOINT=https://your-account-id.r2.cloudflarestorage.com
R2_BUCKET_NAME=
R2_PUBLIC_URL=https://your-public-url.r2.dev

Without a bucket, yarn seed stores every product and category image as a /mock-media/… path, and both frontends ship those 35 files in public/mock-media/, so the catalogue renders with nothing uploaded. Only uploading new images stops working: it answers 503 until the bucket is set.

With a bucket, the seed uploads its catalogue images there. Keep public/mock-media/ in both frontends for as long as any product still points at it.

Card payments

Card payments run on Stripe: STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET in back-end/.env, and NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY for the storefront. Without them no card payment is taken, and cash on delivery works as usual.

STRIPE_SECRET_KEY=sk_test_your-stripe-secret-key
STRIPE_WEBHOOK_SECRET=whsec_your-webhook-secret

• Set up Stripe

Email

The template ships no mail transport, so no message is ever emailed. Outside production, a customer's password-reset token is written to the API's log instead; with NODE_ENV=production it goes nowhere. Connect your own mail provider before going live: the hook is forgotPassword in back-end/src/modules/customer-auth/customer-auth.controller.ts.

• Customer accounts

AI features

The sample store in the frontends

Both frontends run without an API. Started or built without NEXT_PUBLIC_API_BASE_URL, each answers every request from a sample store in the browser and shows a "Sample data" notice. Setting the address is what switches it off.

• Any email and password sign in as the sample shopper on the storefront. In the dashboard, any valid email with a password of at least 6 characters signs in as the Super Admin.
• Writes are real and are kept in the browser's storage, so they survive a reload. To start over, run localStorage.removeItem("mock_db_v1"); location.reload(); in the browser console.
• Checkout on the storefront completes without calling Stripe.
• In the dashboard, the AI assistant and the AI studio stay unavailable, because both need the API's keys.
• Once your API is live, yarn remove:mock in either app deletes the sample store and its notice. It leaves public/mock-media/ in place, because a backend seeded without a bucket points its images there.

How the sample store works

Demo mode

Going live

Before you deploy anywhere public:

1. Set NODE_ENV=production and a long random JWT_SECRET of your own in back-end/.env.
2. Set CORS_ORIGIN to your storefront's and admin's addresses, comma separated, and FRONTEND_URL to the admin's address.
3. On an empty database, run yarn build, then yarn db:sync:prod once (or yarn seed:prod for the demo store), then yarn start:prod.
4. Point your host's health check at /api/health.
5. Build each frontend with NEXT_PUBLIC_API_BASE_URL at your deployed API and the storefront's NEXT_PUBLIC_SITE_URL at its own address.
6. Change the Super Admin's password, or start from empty tables.