diff --git a/.env.example b/.env.example
new file mode 100644
index 000000000..abf8c4034
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,38 @@
+# emaui environment
+#
+# Vite reads this from the workspace root, not from the app directory:
+# apps/portal/vite.config.mts and apps/backoffice/vite.config.mts both set
+# `envDir: '../../'`. So copy this file to ./.env here, at the repo root.
+#
+#   cp .env.example .env
+#
+# Only VITE_-prefixed values reach the browser, and everything that does is
+# public — it ships inside the built bundle. Never put a secret here. The Fayda
+# client id, private key and endpoints live in the API's environment only; the
+# frontend never speaks to Fayda directly.
+
+# Base URL of the emaapi backend, including the /api prefix.
+# Defaults to http://localhost:3000/api when unset.
+VITE_BASE_API_URL=http://localhost:3000/api
+
+# Serve fixture data instead of calling the API. Any value other than "true"
+# uses the real backend.
+VITE_USE_MOCKS=false
+
+# --- Docker Compose only -----------------------------------------------------
+# Host ports published by docker-compose.yml. It also expects per-app env files
+# at apps/portal/.env and apps/backoffice/.env, which can each be a copy of this
+# file. Ignored when running the Vite dev servers, which serve the portal on
+# 4200 and the backoffice on 4201.
+# EMA_PORTAL_PORT=8021
+# EMA_BACKOFFICE_PORT=8022
+
+# --- Fayda note --------------------------------------------------------------
+# There is nothing to configure here for Fayda. The portal serves the callback
+# page at /callback and /signup/fayda/callback, and whichever path is registered
+# with Fayda must match the API's FAYDA_REDIRECT_URI exactly.
+#
+# The value being registered first is http://localhost:3000/callback, which is
+# also emaapi's default port — so when testing that redirect, serve the portal
+# on 3000 (`npx nx serve portal --port 3000`) and move the API elsewhere, or
+# register a URI that points at the port the portal actually runs on.
diff --git a/.gitignore b/.gitignore
index 4b15bf545..8b70b3e9d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,6 +13,8 @@ coverage/
 # env
 .env
 .env.*
+# ...but the checked-in template must survive that rule.
+!.env.example
 
 # logs
 *.log