Nitty Music Social Management
Nitty Music Social Management

Configuration

Configuration Reference

Environment variables reference for Nitty Music Social

Nitty Music Social 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 Nitty Music Social reads, grouped by purpose.

Variables marked Required are validated on boot: Nitty Music Social 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 Nitty Music Social frontend. Used as the OAuth redirect base and for email links.

FRONTEND_URL="https://social.example.com"

NEXT_PUBLIC_BACKEND_URL Required

The URL the browser uses to reach the Nitty Music Social backend.

NEXT_PUBLIC_BACKEND_URL="https://api.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. It is a single value for the whole instance and does not tier by plan: channel and post quotas do that instead.

Note that the shipped docker-compose.yaml sets API_LIMIT: 30, which is lower than the default. Raise it if you drive Nitty Music Social from scripts.

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

Branding and product-line switch. It controls page titles, which sign-in providers are offered, the default landing route, and a handful of labels. Set it to "true", which is what the shipped compose file does.

IS_GENERAL is not the cloud switch, despite the name. Plans, limits and billing are enabled by the presence of STRIPE_PUBLISHABLE_KEY, so an install without a Stripe key has no plan gating at all and behaves as the top tier.

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.

DISABLE_SSRF_PROTECTION

When connecting providers that take a self-hosted URL (WordPress, Mastodon, Lemmy, Listmonk, Bluesky PDS, etc.), posting media to such providers, fetching webhooks, or handling /public/v1/upload-from-url, Nitty Music Social fetches the URL server-side and blocks requests that resolve to private, internal, loopback, or link-local IPs to prevent SSRF. Blocked requests surface as fetch failed with Error: Blocked IP in the backend or orchestrator logs. Set to true to disable the guard. Set it on both the backend and orchestrator containers.

This disables SSRF protection globally, not per provider. Only set it if your Nitty Music Social instance must reach those services on a trusted private network (e.g. same Docker network, VPC, or homelab LAN) and all users of the instance are trusted (single-tenant). Any user who can submit a URL can make the server fetch internal services. Prefer fixing DNS/routing so the hostname resolves to a reachable address.

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, Nitty Music Social 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.
EXCLUDE_QUEUE Comma-separated list of per-platform task queues this worker should not handle, for example "reddit,x,twitch". Use it to pin slow or rate-limited platforms to a dedicated worker.
WORKER_CONCURRENCY_DIVIDER Divides each platform’s configured concurrency, so several workers can share a queue without exceeding the platform’s limits. Defaults to 1.
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.
RUNPOD_API_KEY RunPod API key with access to the clipping endpoints. See Video clipping.
RUNPOD_INGEST_ENDPOINT_ID RunPod endpoint (CPU) that runs the ingest jobs of video clipping.
RUNPOD_CLIPPER_ENDPOINT_ID RunPod endpoint (GPU) that renders the clips of video clipping.
DEEPGRAM_API_KEY Deepgram key that transcribes videos without usable captions for video clipping.

If a Nitty Music Social user configures short-link replacement, Nitty Music Social 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

SHORT_IO_SECRET_KEY=""

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
Almost no self-hosted install needs these. Setting STRIPE_PUBLISHABLE_KEY switches the whole application into billed mode, which means plans, channel caps and AI credits start being enforced against subscriptions you have no way to sell. Leave the whole section unset unless you are deliberately running a paid service.
Variable Purpose
STRIPE_PUBLISHABLE_KEY Stripe publishable key. Presence of this variable is what enables billing, plans and limits.
STRIPE_SECRET_KEY Stripe secret key.
STRIPE_SIGNING_KEY Stripe webhook signing key for subscription events.
STRIPE_DISCOUNT_ID Discount offered when a customer starts to cancel.

Removed

These appear in older .env examples and in the shipped compose file, but nothing in Nitty Music Social reads them any more. Delete them.

STRIPE_SIGNING_KEY_CONNECT, FEE_AMOUNT, NOWPAYMENTS_API_KEY, NOWPAYMENTS_AMOUNT, SLACK_SIGNING_SECRET, NX_ADD_PLUGINS

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.
CHATBASE_TOKEN Enables the in-app AI support chat instead of the Discord button. Cloud only in practice, since the chat can act on billing.
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 /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
Tumblr TUMBLR_CLIENT_ID, TUMBLR_CLIENT_SECRET /providers/tumblr
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.