diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..da069de
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,49 @@
+# Homepage secrets / environment variables
+#
+# IMPORTANT: This file must be copied/renamed to ".env" and placed in the
+# PROJECT ROOT (/opt/homepage/.env), NOT inside this config/ directory.
+# Homepage reads HOMEPAGE_VAR_* values from the running process's
+# environment (process.env). Next.js only auto-loads a ".env" file from
+# its working directory (the project root, where "pnpm start" runs from,
+# see WorkingDirectory in the homepage.service systemd unit) - it does
+# NOT read anything from config/.
+#
+# After editing the real .env, restart the service for changes to take
+# effect (values are only read once, at process start):
+#   systemctl restart homepage.service
+#
+# In services.yaml / proxmox.yaml, reference these as {{HOMEPAGE_VAR_XXX}}.
+# Do not commit the real .env file - only this .example file is tracked.
+
+# --- Proxmox VE (proxmox.yaml + Proxmox VE / Proxmox Storage widgets in services.yaml) ---
+# API token ID and secret, created in Proxmox under Datacenter > Permissions > API Tokens
+HOMEPAGE_VAR_PROXMOX_USERNAME=user@pam!tokenid
+HOMEPAGE_VAR_PROXMOX_PASSWORD=your-proxmox-api-token-secret
+# Same token, pre-formatted as the PVEAPIToken header value used by the
+# customapi Proxmox Storage widgets: PVEAPIToken=<username>=<password>
+HOMEPAGE_VAR_PROXMOX_PVE_AUTH=PVEAPIToken=user@pam!tokenid=your-proxmox-api-token-secret
+
+# --- Unifi Controller widget ---
+# API key, created in the Unifi Controller under Settings > Control Plane > Integrations
+HOMEPAGE_VAR_UNIFI_KEY=your-unifi-api-key
+
+# --- AdGuard Home widget ---
+# Local AdGuard Home admin account (same login used for the web UI)
+HOMEPAGE_VAR_ADGUARD_USERNAME=your-adguard-username
+HOMEPAGE_VAR_ADGUARD_PASSWORD=your-adguard-password
+
+# --- Synology Diskstation widget ---
+# DSM account with admin group membership; 2FA must be disabled for this account
+HOMEPAGE_VAR_SYNOLOGY_USERNAME=your-synology-username
+HOMEPAGE_VAR_SYNOLOGY_PASSWORD=your-synology-password
+
+# --- Beszel widget ---
+# Beszel superuser account (email + password), must be able to log in at
+# <beszel-url>/_/#/login
+HOMEPAGE_VAR_BESZEL_USERNAME=your-beszel-email
+HOMEPAGE_VAR_BESZEL_PASSWORD=your-beszel-password
+
+# --- Patchmon customapi widget ---
+# Full HTTP Basic Authorization header value (including "Basic " prefix),
+# base64 of "<patchmon_api_key>:<patchmon_api_secret>" as provided by Patchmon
+HOMEPAGE_VAR_PATCHMON_AUTH=Basic base64EncodedCredentialsHere