Dokumentation

Umgebungsvariablen

Erforderliche und optionale Umgebungsvariablen für Motoko Base — Datenbank, Auth, Billing, E-Mail, Storage, Analytics, Monitoring und KI.

Öffnen inChatGPT Claude Cursor

Motoko Base liest die Konfiguration aus Umgebungsvariablen. Kopieren Sie .env.example nach .env oder .env.local und füllen Sie die Werte aus:

cp .env.example .env

Committen Sie niemals echte Secrets. .env* ist gitignored außer .env.example. Legen Sie niemals server-only Secrets auf NEXT_PUBLIC_* — sie werden im Browser exponiert.

Optionale Integrationen soft-failen, wenn sie nicht gesetzt sind: die App startet, unabhängige Routen bleiben funktionsfähig, und Feature-Seiten zeigen eine klare Konfigurationsmeldung statt abzustürzen.

Erforderlich

Diese drei Variablen reichen aus, um den Dev-Server zu starten und Migrationen auszuführen:

Variable	Required	Purpose
`DATABASE_URL`	Yes	PostgreSQL connection string (server-only)
`BETTER_AUTH_SECRET`	Yes	Signing secret for sessions and tokens
`BETTER_AUTH_URL`	Yes	Public origin for auth callbacks — use `http://localhost:3000` locally

Secret erzeugen:

openssl rand -base64 32

Stark empfohlen

E-Mail-Verifizierung ist erforderlich, bevor der Dashboard-Zugang möglich ist. Ohne konfiguriertes Resend können Sie die App starten, erhalten nach der Registrierung aber keine Verifizierungs-E-Mails.

Variable	Required	Purpose
`RESEND_API_KEY`	Recommended	Resend API key for transactional email
`EMAIL_FROM`	Recommended	Sender address, e.g. `Motoko Base <onboarding@resend.dev>` for Resend onboarding tests

Anwendung

Variable	Required	Purpose
`NEXT_PUBLIC_APP_URL`	No	Public app origin for short links (`/r/{slug}`) and password-reset redirects. Falls back to the request origin when unset. Keep aligned with `BETTER_AUTH_URL` in production.

Authentifizierung

Variable	Required	Purpose
`BETTER_AUTH_SECRET`	Yes	Session and token signing secret
`BETTER_AUTH_URL`	Yes	Canonical auth origin (must match the URL users hit for callbacks)
`BETTER_AUTH_TRUSTED_ORIGINS`	No	Comma-separated extra origins for preview/staging hosts
`GOOGLE_CLIENT_ID`	No	Google OAuth client ID — leave unset to disable Google sign-in
`GOOGLE_CLIENT_SECRET`	No	Google OAuth client secret
`GITHUB_CLIENT_ID`	No	GitHub OAuth app client ID — leave unset to disable GitHub sign-in
`GITHUB_CLIENT_SECRET`	No	GitHub OAuth app client secret

OAuth-Callback-URLs müssen zu BETTER_AUTH_URL passen:

Google: {BETTER_AUTH_URL}/api/auth/callback/google
GitHub: {BETTER_AUTH_URL}/api/auth/callback/github

Datenbank

Variable	Required	Purpose
`DATABASE_URL`	Yes	PostgreSQL connection string (Supabase or local). Never `NEXT_PUBLIC_*`.

Für Supabase zur Laufzeit bevorzugen Sie den Transaction Pooler (oft Port 6543). Schlagen Migrationen über den Pooler fehl, zeigen Sie DATABASE_URL vorübergehend auf die direkte Verbindung (oft Port 5432). Siehe src/lib/db/README.md.

Billing

Variable	Required	Purpose
`BILLING_PROVIDER`	No	Billing provider selection (`polar` in v1). Defaults to `polar`.
`POLAR_ACCESS_TOKEN`	No	Polar Organization Access Token — leave unset to stay on Free
`POLAR_WEBHOOK_SECRET`	No	Webhook secret from Polar → Settings → Webhooks
`POLAR_PRO_MONTHLY_PRODUCT_ID`	No	Pro monthly product ID from Polar Dashboard
`POLAR_PRO_YEARLY_PRODUCT_ID`	No	Pro yearly product ID (optional)
`POLAR_SERVER`	No	`sandbox` or `production` (tokens and products are environment-specific)

Webhook-Endpoint: {APP_URL}/api/billing/webhooks/polar

E-Mail

Variable	Required	Purpose
`RESEND_API_KEY`	No*	Resend API key (server-only)
`EMAIL_FROM`	No*	Single sender identity, e.g. `Motoko Base <noreply@yourdomain.com>`

* Beide werden für die E-Mail-Zustellung benötigt. Die App startet ohne sie, aber die Registrierungs-Verifizierung funktioniert nicht.

Storage

Cloudflare R2 betreibt die File-Storage-Demo und Avatar-Uploads. Ungesetzt lassen, um ohne Storage zu booten.

Variable	Required	Purpose
`R2_ACCOUNT_ID`	No	Cloudflare account ID (used to build the S3 API endpoint)
`R2_ACCESS_KEY_ID`	No	R2 API token access key
`R2_SECRET_ACCESS_KEY`	No	R2 API token secret
`R2_BUCKET_NAME`	No	Private bucket name. A slash is treated as an object-key prefix: `my-bucket/demo` → bucket `my-bucket`, prefix `demo/`
`R2_PREFIX`	No	Optional explicit object-key prefix (overrides a slash suffix on the bucket name)
`R2_ENDPOINT`	No	Optional S3 API endpoint override (defaults from `R2_ACCOUNT_ID`)

Analytics

PostHog ist aufgeteilt in Client-Capture (Project Token) und Server-HogQL-Queries (Personal API Key).

Variable	Required	Purpose
`NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN`	No	PostHog project API key for client capture
`NEXT_PUBLIC_POSTHOG_HOST`	No	Ingest host (US default: `https://us.i.posthog.com`, EU: `https://eu.i.posthog.com`)
`POSTHOG_PERSONAL_API_KEY`	No	Personal API key with Query Read — used by `/dashboard/analytics`
`POSTHOG_PROJECT_ID`	No	PostHog project ID for HogQL queries
`POSTHOG_HOST`	No	App API host for Query API (US: `https://us.posthog.com`, EU: `https://eu.posthog.com`)

Monitoring

Variable	Required	Purpose
`NEXT_PUBLIC_SENTRY_DSN`	No	Public Sentry DSN — leave unset to disable monitoring
`SENTRY_AUTH_TOKEN`	No	Auth token for source map upload during `next build`
`SENTRY_ORG`	No	Sentry organization slug
`SENTRY_PROJECT`	No	Sentry project slug

Sentry wird auch automatisch während next dev deaktiviert (selbst wenn die DSN gesetzt ist), um Webpack-Listener-Rauschen zu vermeiden.

KI

Variable	Required	Purpose
`OPENAI_API_KEY`	No	OpenAI or compatible API key — leave unset to disable AI Email demo
`OPENAI_BASE_URL`	No	Optional OpenAI-compatible API base URL
`OPENAI_MODEL`	No	Model ID (defaults to `gpt-4o-mini`)

Schnellreferenz nach Boot-Anforderung

Category	Minimal boot	Full feature set
Database	`DATABASE_URL`	`DATABASE_URL`
Authentication	`BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`	+ optional OAuth vars
Email	—	`RESEND_API_KEY`, `EMAIL_FROM`
Billing	—	`POLAR_*` vars
Storage	—	`R2_*` vars
Analytics	—	PostHog vars
Monitoring	—	Sentry vars
AI	—	`OPENAI_API_KEY`

Siehe .env.example für Inline-Kommentare zu jeder Variable.

Nächste Schritte

Konfiguration — Wo Config-Dateien liegen und wie Navigation, Billing-Pläne, Metadata und Integrationen geändert werden.