Postiz is configured entirely through environment variables. Any change requires
an application restart.
The canonical list lives in the example postiz.env file.
This page documents every variable Postiz reads, grouped by purpose.
Variables marked Required are validated on boot — Postiz will fail to start
if they’re missing or malformed.
Required core
These six variables are non-optional for any deployment.
DATABASE_URL Required
PostgreSQL connection string used by Prisma.
DATABASE_URL="postgresql://postiz-user:postiz-password@localhost:5432/postiz-db-local"
REDIS_URL Required
Redis connection string used for queues, rate limiting, and short-lived caches.
REDIS_URL="redis://localhost:6379"
JWT_SECRET Required
A long random string used to sign session JWTs. Rotating this invalidates every existing session.
FRONTEND_URL Required
The URL the browser uses to reach the Postiz frontend. Used as the OAuth redirect base and for email links.
FRONTEND_URL="https://postiz.example.com"
NEXT_PUBLIC_BACKEND_URL Required
The URL the browser uses to reach the Postiz backend.
NEXT_PUBLIC_BACKEND_URL="https://api.postiz.example.com"
BACKEND_INTERNAL_URL Required
The URL the frontend SSR server uses to reach the backend from inside your network. If everything runs in the same container/host, this is usually http://localhost:3000.
Application behaviour
DISABLE_REGISTRATION
Set to true to allow only a single user signup and then disable the sign-up page. Useful for self-host where you want full control.
This also disables OIDC / OAuth sign-in.
API_LIMIT
Per-hour limit on the public-API create-post endpoint. Defaults to 90. Postiz Cloud uses 100. Channel and post quotas are tiered separately by plan.
RUN_CRON
When set, the backend process runs the scheduled-task workers. Leave unset on API-only instances when workers are deployed separately.
RESTRICT_UPLOAD_DOMAINS
Comma-separated allowlist of domains for /public/v1/upload-from-url. If set, only URLs whose hostname matches an entry are accepted.
DISALLOW_PLUS
When set, blocks the upgrade UI elements pointing to paid plans. Used for self-host deployments that don’t want to surface cloud-only billing.
IS_GENERAL
Switches the frontend between routes available to the open-source build (/launches) and the hosted build (/analytics). Set to "true" on self-host. Leave unset on Postiz Cloud.
DISABLE_IMAGE_COMPRESSION
When truthy, the frontend skips client-side image compression on upload. Set this if you need pixel-exact originals at the cost of larger uploads.
NOT_SECURED
Dev only. Never set in production — it disables security checks that exist for a reason.
MAIN_URL
Primary application URL used for absolute links in some emails and SEO metadata. Falls back to FRONTEND_URL when not set.
EXTENSION_ID
The Chrome Extension ID for cookie-based platform integrations (e.g. Skool). See the Chrome Extension guide.
MOBILE_APP_SCHEME
URL scheme used for deep-linking from emails into the mobile app.
Storage
See also: Cloudflare R2 and Uploads & Storage.
| Variable | Purpose |
|---|
STORAGE_PROVIDER | local or cloudflare. Defaults to local. |
UPLOAD_DIRECTORY | Filesystem path for local storage writes. |
NEXT_PUBLIC_UPLOAD_STATIC_DIRECTORY | Public URL prefix the frontend uses to reference uploaded files. |
CLOUDFLARE_ACCOUNT_ID | R2 account ID. |
CLOUDFLARE_ACCESS_KEY | R2 access key. |
CLOUDFLARE_SECRET_ACCESS_KEY | R2 secret access key. |
CLOUDFLARE_BUCKETNAME | R2 bucket name. |
CLOUDFLARE_BUCKET_URL | Public-facing URL the bucket is served from. |
CLOUDFLARE_REGION | R2 region (usually auto). |
Email
See also: Email configuration.
| Variable | Purpose |
|---|
EMAIL_PROVIDER | resend (default) or nodemailer. |
RESEND_API_KEY | Resend API key — required when EMAIL_PROVIDER=resend. Presence of this variable also gates whether user activation is required (set → required; unset → users are auto-activated). |
EMAIL_HOST | SMTP host — required when EMAIL_PROVIDER=nodemailer. |
EMAIL_PORT | SMTP port. |
EMAIL_USER | SMTP user. |
EMAIL_PASS | SMTP password. |
EMAIL_SECURE | true for SMTPS / implicit TLS. |
EMAIL_FROM_ADDRESS | From-address used on all outgoing email. |
EMAIL_FROM_NAME | From-name used on all outgoing email. |
OAuth sign-in (OIDC)
See also: OAuth configuration.
| Variable | Purpose |
|---|
POSTIZ_GENERIC_OAUTH | true to enable a generic OIDC sign-in provider. |
POSTIZ_OAUTH_URL | Base URL of the IdP. |
POSTIZ_OAUTH_AUTH_URL | Authorization endpoint. |
POSTIZ_OAUTH_TOKEN_URL | Token endpoint. |
POSTIZ_OAUTH_USERINFO_URL | UserInfo endpoint. |
POSTIZ_OAUTH_CLIENT_ID | Client ID issued by the IdP. |
POSTIZ_OAUTH_CLIENT_SECRET | Client secret issued by the IdP. |
POSTIZ_OAUTH_SCOPE | OIDC scope. Defaults to openid profile email. |
NEXT_PUBLIC_POSTIZ_OAUTH_DISPLAY_NAME | Label shown on the sign-in button. |
NEXT_PUBLIC_POSTIZ_OAUTH_LOGO_URL | Icon shown on the sign-in button. |
Temporal (workflow orchestration)
Since v2.12.0, Postiz uses Temporal for scheduled posts and background workflows.
Self-host deployments need to run a Temporal stack (the official docker-compose
ships with one). See the Temporal migration guide.
| Variable | Purpose |
|---|
TEMPORAL_ADDRESS | host:port of the Temporal frontend. |
TEMPORAL_NAMESPACE | Temporal namespace to run workflows in. |
TEMPORAL_API_KEY | API key for Temporal Cloud. Leave unset for self-host. |
TEMPORAL_TLS | true to require TLS to the Temporal frontend. |
ORCHESTRATOR_PORT | Port the in-process orchestrator binds to. |
Public API & MCP
| Variable | Purpose |
|---|
MCP_URL | URL the frontend uses to advertise the MCP endpoint to clients. |
AGENT_API_KEY | Shared secret used by the agent runtime to call privileged endpoints. |
AGENT_MEDIA_SSO_KEY | Signing key for short-lived agent-media SSO tokens. |
BACKEND_URL | Legacy alias for NEXT_PUBLIC_BACKEND_URL in a few server contexts. |
AI / generation
| Variable | Purpose |
|---|
OPENAI_API_KEY | OpenAI key used for the copilot and AI image generation. |
OPENAI_APP_CHALLANGE | Verification challenge string for the OpenAI custom GPT integration. |
ELEVENSLABS_API_KEY | ElevenLabs API key for voice generation. |
FAL_KEY | fal.ai API key for image/video models. |
TAVILY_API_KEY | Tavily search API key used by the research tool. |
KIEAI_API_KEY | KieAI API key. |
TRANSLOADIT_AUTH | Transloadit auth key for video pipelines. |
TRANSLOADIT_SECRET | Transloadit signing secret. |
TRANSLOADIT_TEMPLATE | Transloadit template ID used by the video generator. |
Short-link providers
If a Postiz user configures short-link replacement, Postiz proxies link
shortening through one of the configured providers. Pick one set.
Dub.co
DUB_TOKEN=""
DUB_API_ENDPOINT="https://api.dub.co"
DUB_SHORT_LINK_DOMAIN="dub.sh"
Short.io
Kutt.it
KUTT_API_KEY=""
KUTT_API_ENDPOINT="https://kutt.it/api/v2"
KUTT_SHORT_LINK_DOMAIN="kutt.it"
LinkDrip
LINK_DRIP_API_KEY=""
LINK_DRIP_API_ENDPOINT="https://api.linkdrip.com/v1/"
LINK_DRIP_SHORT_LINK_DOMAIN="dripl.ink"
Payments
| Variable | Purpose |
|---|
STRIPE_PUBLISHABLE_KEY | Stripe publishable key. |
STRIPE_SECRET_KEY | Stripe secret key. |
STRIPE_SIGNING_KEY | Stripe webhook signing key for subscription events. |
STRIPE_SIGNING_KEY_CONNECT | Stripe Connect webhook signing key. |
STRIPE_DISCOUNT_ID | Default Stripe discount applied to new subscriptions. |
FEE_AMOUNT | Platform fee fraction (e.g. 0.05). |
NOWPAYMENTS_API_KEY | NOWPayments API key for crypto checkout. |
NOWPAYMENTS_AMOUNT | Default NOWPayments invoice amount. |
Analytics & tracking (frontend)
All of these are optional. Frontend reads NEXT_PUBLIC_* at build time.
| Variable | Purpose |
|---|
NEXT_PUBLIC_SENTRY_DSN | Frontend Sentry DSN. |
NEXT_PUBLIC_GTM_ID | Google Tag Manager container ID. |
NEXT_PUBLIC_FACEBOOK_PIXEL | Facebook Pixel ID. |
FACEBOOK_PIXEL_ACCESS_TOKEN | Server-side Pixel Conversions API token. |
NEXT_PUBLIC_POSTHOG_HOST | PostHog host (e.g. https://eu.posthog.com). |
NEXT_PUBLIC_POSTHOG_KEY | PostHog project API key. |
NEXT_PUBLIC_TRACKING_TRIAL | When set, enables trial-funnel tracking events. |
DATAFAST_API_KEY | Datafast analytics API key. |
DATAFAST_WEBSITE_ID | Datafast website ID. |
SENTRY_AUTH_TOKEN | Build-time Sentry token for sourcemap upload. |
SENTRY_ORG | Sentry org slug. |
SENTRY_PROJECT | Sentry project slug. |
SENTRY_SPOTLIGHT | Enable Sentry Spotlight in dev. |
Misc frontend
| Variable | Purpose |
|---|
NEXT_PUBLIC_DISCORD_SUPPORT | Discord invite URL shown in the support widget. |
NEXT_PUBLIC_POLOTNO | Polotno API key for the image editor. |
NEXT_PUBLIC_VERSION | Version string shown in the footer. |
NEXT_PUBLIC_APP_VERSION | Mobile/web version label. |
NEXT_PUBLIC_OVERRIDE_BACKEND_URL | When set, overrides NEXT_PUBLIC_BACKEND_URL at runtime. Useful for tunnel-based dev. |
Social provider keys
Each social provider has its own env-var block. See the per-provider setup
pages under Providers for the exact OAuth steps; this
table is just a lookup so you can find which page documents which variable.
| Provider | Variables | Setup |
|---|
| X (Twitter) | X_API_KEY, X_API_SECRET, X_URL, DISABLE_X_ANALYTICS, STRIP_LINKS_FROM_X_POSTS | /providers/x-twitter |
| LinkedIn | LINKEDIN_CLIENT_ID, LINKEDIN_CLIENT_SECRET | /providers/linkedin, /providers/linkedin-page |
| Facebook / Instagram (FB) | FACEBOOK_APP_ID, FACEBOOK_APP_SECRET | /providers/facebook, /providers/instagram |
| Instagram (Standalone) | INSTAGRAM_APP_ID, INSTAGRAM_APP_SECRET | /providers/instagram |
| Threads | THREADS_APP_ID, THREADS_APP_SECRET | /providers/threads |
| YouTube | YOUTUBE_CLIENT_ID, YOUTUBE_CLIENT_SECRET | /providers/youtube |
| Google My Business | GOOGLE_GMB_CLIENT_ID, GOOGLE_GMB_CLIENT_SECRET | /providers/google-my-business |
| TikTok | TIKTOK_CLIENT_ID, TIKTOK_CLIENT_SECRET | /providers/tiktok |
| Reddit | REDDIT_CLIENT_ID, REDDIT_CLIENT_SECRET | /providers/reddit |
| Pinterest | PINTEREST_CLIENT_ID, PINTEREST_CLIENT_SECRET | /providers/pinterest |
| Discord | DISCORD_CLIENT_ID, DISCORD_CLIENT_SECRET, DISCORD_BOT_TOKEN_ID | /providers/discord |
| Slack | SLACK_ID, SLACK_SECRET, SLACK_SIGNING_SECRET | /providers/slack |
| Telegram | TELEGRAM_TOKEN, TELEGRAM_BOT_NAME | /providers/telegram |
| Mastodon | MASTODON_URL, MASTODON_CLIENT_ID, MASTODON_CLIENT_SECRET | /providers/mastodon |
| Dribbble | DRIBBBLE_CLIENT_ID, DRIBBBLE_CLIENT_SECRET | /providers/dribbble |
| Farcaster | NEYNAR_CLIENT_ID, NEYNAR_SECRET_KEY, NEYNAR_LOGIN_URL | /providers/farcaster |
| MeWe | MEWE_HOST, MEWE_APP_ID, MEWE_API_KEY | /providers/mewe |
| Twitch | TWITCH_CLIENT_ID, TWITCH_CLIENT_SECRET | API only — see /public-api/providers/twitch |
| Kick | KICK_CLIENT_ID, KICK_SECRET | API only — see /public-api/providers/kick |
| VK | VK_ID | API only — see /public-api/providers/vk |
| Whop | WHOP_CLIENT_ID | /providers/whop |
| GitHub (sign-in) | GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET | /configuration/oauth |
| Beehiiv | BEEHIIVE_API_KEY, BEEHIIVE_PUBLICATION_ID | Newsletter provider |
| Listmonk | LISTMONK_DOMAIN, LISTMONK_USER, LISTMONK_API_KEY, LISTMONK_LIST_ID, LISTMONK_WELCOME_TEMPLATE_ID | Newsletter provider |
Runtime & build
These are read from the environment but are typically managed by your runtime,
hosting platform, or framework rather than set by hand.
| Variable | Purpose |
|---|
PORT | Port the backend HTTP server binds to. Defaults to 3000. |
TZ | Process timezone. The backend forces this to UTC on boot. |
NODE_ENV | Standard Node environment flag (development / production). Toggles dev-only behaviour like sourcemaps. |
NEXT_RUNTIME | Set by Next.js (nodejs / edge) to select the instrumentation hook. Framework-injected — do not set manually. |
VERCEL_GIT_COMMIT_SHA | Commit SHA used as the Sentry release tag on the frontend. Injected by Vercel. |
GITHUB_SHA | Fallback commit SHA for the Sentry release tag when not on Vercel. Injected by GitHub Actions. |
