Environment Variables

Sitepins configuration is managed through standard environment variables across two files:

api/.env: Express backend server, database, authentication, object storage, and mail settings. Single source of truth is parsed at api/src/config/variables.ts.
app/.env: Next.js web application, provider OAuth credentials, WebSocket URLs, and white-label branding tokens.

Values That Must Agree Across Services

A mismatch in any of these variables between api/.env and app/.env will cause session drops, token rejections, or broken preview sandboxes:

Setting	`app/.env`	`api/.env`	Behavior if mismatched
Internal Secret	`INTERNAL_API_SECRET`	`INTERNAL_API_SECRET`	Must be identical. Mismatch produces `401 Unauthorized` on preview and verification calls.
API Base URL	`NEXT_PUBLIC_BACKEND_URL`	Derived from `BASE_URL`	Must point to the reachable API address.
Cookie Domain	Unset (single host)	`COOKIE_DOMAIN`	If set on API, must match root domain (e.g. `.example.com`) across both web and API subdomains.
Bucket URL	`NEXT_PUBLIC_BUCKET_URL`	Must match `S3_BUCKET_NAME` & endpoint	Avatars/thumbnails upload successfully via API but render as broken 404 images in the UI.

Backend Environment Variables (`api/.env`)

1. Server Configuration

Variable	Required	Default	Description
`PORT`	Optional	`4000`	Port on which the Express API listens.
`NODE_ENV`	Required	`development`	Runtime environment: `development` or `production`.
`BASE_URL`	Required	`http://localhost:4000`	The public URL of the API. Better Auth uses this to construct OAuth callback URLs.
`MONGO_URI`	Required	—	MongoDB connection string (e.g. `mongodb://localhost:27017/sitepins`).
`CORS_ORIGINS`	Required (prod)	—	Comma-separated list of browser origins allowed to make credentialed requests (e.g. `https://cms.example.com`). Ignored in local dev.
`TRUST_PROXY`	Optional	`1` (prod) / off (dev)	Reverse proxy hops. Set to `1` when behind Nginx, Caddy, or Cloudflare; set to `false` if exposed directly.
`JSON_BODY_LIMIT`	Optional	`5mb`	Maximum permitted request payload body size.

2. Authentication & Cryptography

Variable	Required	Default	Description
`BETTER_AUTH_SECRET`	Required	—	High-entropy session signing key (`openssl rand -base64 32`). Crashes startup in production if missing.
`JWT_SECRET`	Required	—	Secret key used to sign internal action tokens (`openssl rand -hex 32`).
`JWT_TOKEN_EXPIRE`	Required	`7d`	Expiration window for internal action tokens (e.g. `1d`, `7d`, `30d`).
`SANDBOX_ENCRYPTION_KEY`	Required	—	32-byte hex key (`openssl rand -hex 32`) used for AES-256-GCM encryption of preview sandbox tokens.
`INTERNAL_API_SECRET`	Required	—	Shared secret string for server-to-server calls (`openssl rand -hex 32`). Must match `app/.env`.
`SALT`	Optional	`10`	Salt work factor for `bcrypt` password hashing.
`COOKIE_DOMAIN`	Optional	unset	Domain scope for session cookies. Leave unset for single-domain installs. Set to leading-dot (e.g. `.example.com`) for cross-subdomain setups.
`RATELIMIT_WINDOW`	Optional	`10`	Rate-limiting sliding window in seconds.
`RATELIMIT_MAX`	Optional	`100`	Maximum requests permitted per IP per rate-limit window.
`REQUIRE_EMAIL_VERIFICATION`	Optional	`true`	Set to `false` to disable OTP verification at signup for closed intranets or local testing.
`DEMO_MODE`	Optional	`false`	When `true`, mounts demo login endpoints for public demonstration instances.

These credentials are used strictly for logging in to the Sitepins interface. They are separate from repository access credentials.

Variable	Required	Description
`GITHUB_CLIENT_ID`	Optional	Client ID from a GitHub OAuth application. Callback: `<BASE_URL>/api/v1/auth/callback/github`.
`GITHUB_CLIENT_SECRET`	Optional	Client secret from your GitHub OAuth application.
`GOOGLE_CLIENT_ID`	Optional	Client ID from Google Cloud Console. Callback: `<BASE_URL>/api/v1/auth/callback/google`.
`GOOGLE_CLIENT_SECRET`	Optional	Client secret from Google Cloud Console.

4. S3 Media Storage

Used for application assets (user profile pictures, organization icons, and project cover images). Site content images remain in your Git repository.

Variable	Required	Description
`S3_ENDPOINT`	Required	S3 gateway endpoint URL (e.g. `https://s3.us-east-1.amazonaws.com` or Cloudflare R2 endpoint).
`S3_REGION`	Required	Storage region (e.g. `us-east-1`, or `auto` for Cloudflare R2).
`S3_ACCESS_KEY`	Required	S3 access key ID.
`S3_SECRET_KEY`	Required	S3 secret access key.
`S3_BUCKET_NAME`	Required	Target bucket name.
`S3_FORCE_PATH_STYLE`	Optional	Set to `true` for MinIO or local path-style gateways (`http://endpoint/bucket`). Default is `false`.

Existing DigitalOcean Spaces setups using DOS_PUBLIC_ACCESS_KEY, DOS_PUBLIC_SECRET_KEY, DOS_BUCKET_NAME, and DOS_REGION remain fully supported and auto-derive the endpoint.

5. Email & SMTP Configuration

Core uses provider-agnostic transactional email with built-in responsive HTML templates:

Variable	Default	Description
`MAIL_PROVIDER`	`console` / `smtp`	Mail driver. Auto-detected as `smtp` if `SMTP_HOST` is present, otherwise defaults to `console`.
`MAIL_FROM_NAME`	`Sitepins`	Sender display name.
`MAIL_FROM_EMAIL`	`noreply@example.com`	“From” email address.
`SMTP_HOST`	—	SMTP relay host (e.g. `smtp.mailgun.org`, `email-smtp.us-east-1.amazonaws.com`, `smtp.resend.com`).
`SMTP_PORT`	`587`	SMTP port (typically `587` for TLS or `465` for SSL).
`SMTP_SECURE`	`false`	Set to `true` for port 465 (SSL/TLS direct); `false` for port 587 (STARTTLS).
`SMTP_USER`	—	SMTP authentication username.
`SMTP_PASS`	—	SMTP authentication password.
`REOON_API_KEY`	—	Optional anti-abuse email validation key at signup. Fails open if omitted or service is unavailable.

Frontend Environment Variables (`app/.env`)

1. Backend Connectivity & WebSockets

Variable	Required	Description
`NEXT_PUBLIC_BACKEND_URL`	Required	Public URL of the Express API (e.g. `http://localhost:4000` or `https://api.example.com`).
`NEXT_PUBLIC_HP_WS_URL`	Required	WebSocket URL for collaborative editing (e.g. `ws://localhost:4000/api/v1/editor/collab` in dev, `wss://api.example.com/api/v1/editor/collab` in prod).
`NEXT_PUBLIC_BUCKET_URL`	Required	Public base URL of your S3 bucket. Also configures the Next.js `next/image` domain allow-list.
`INTERNAL_API_SECRET`	Required	Must match `INTERNAL_API_SECRET` in `api/.env` identically.
`NEXT_PUBLIC_DASHBOARD_HOME`	Optional	Default redirect route after login (default: `/dashboard/account`).

2. Git Provider Applications (App-Side Only)

These credentials belong strictly to the web app for reading and committing to repositories. The API never holds your private keys.

Variable	Required	Description
`GITHUB_APP_ID`	Required for GH	Numeric App ID from your GitHub App settings page.
`GITHUB_APP_CLIENT_ID`	Required for GH	Client ID from your GitHub App.
`GITHUB_APP_CLIENT_SECRET`	Required for GH	Client secret generated for your GitHub App.
`GITHUB_APP_PRIVATE_KEY`	Required for GH	Full contents of the downloaded `.pem` private key, including `BEGIN` and `END` headers. Quote with double quotes to preserve newlines.
`NEXT_PUBLIC_GITHUB_APP_NAME`	Required for GH	The exact name of your GitHub App (used to construct the installation URL).
`NEXT_PUBLIC_GITLAB_APP_NAME`	Optional	Display name for the GitLab integration in the UI.
`NEXT_PUBLIC_GITLAB_CLIENT_ID`	Required for GL	Application ID from your GitLab OAuth application.
`GITLAB_CLIENT_SECRET`	Required for GL	Secret from your GitLab OAuth application.

3. Artificial Intelligence (BYOK & Server Defaults)

By default, Sitepins is privacy-first: users input their own API keys in their browser (/dashboard/ai-agent), and keys are saved in local storage. You can optionally configure server-wide fallback keys:

Variable	Default	Description
`AI_PROVIDER`	`groq`	Server fallback provider: `groq`, `openrouter`, `openai`, `gemini`, `anthropic`, or `xai`.
`AI_MODEL`	Provider default	Specific model override (e.g. `llama-3.3-70b-versatile`, `gpt-4o-mini`, `gemini-2.5-flash`).
`AI_API_KEY`	—	Server-wide API key. Enables AI features for all users without requiring personal keys.

4. White-Label Branding

Sitepins supports complete white-label customization without modifying application source code:

Variable	Default	Description
`NEXT_PUBLIC_BRAND_NAME`	`Sitepins`	Brand title displayed in headers, titles, and legal footers.
`NEXT_PUBLIC_BRAND_URL`	`https://sitepins.com`	Homepage link for the brand.
`NEXT_PUBLIC_SUPPORT_URL`	`<BRAND_URL>/contact`	URL for the “Support” navigation item.
`NEXT_PUBLIC_UPDATES_URL`	`https://updates.sitepins.com`	URL for changelog and release updates.
`NEXT_PUBLIC_COMMUNITY_URL`	`https://discord.gg/KrpvHfqcNA`	Community or Discord invitation link.
`NEXT_PUBLIC_GIT_COMMIT_EMAIL_DOMAIN`	Host of `BRAND_URL`	Email domain used for Git commit author attribution (e.g. `user@example.com`).

5. Demo Mode

Variable	Default	Description
`NEXT_PUBLIC_IS_DEMO`	`false`	Enables a one-click read-only login button on the sign-in screen.
`NEXT_PUBLIC_DEMO_EMAIL`	—	Pre-populated demo account email address.
`NEXT_PUBLIC_DEMO_PASSWORD`	—	Pre-populated demo account password.

When running in Demo Mode, both DEMO_MODE=true in api/.env and NEXT_PUBLIC_IS_DEMO=true in app/.env must be enabled together.