Environment variables

Pinwren validates its configuration when it starts. A missing or invalid value stops the server with one message that lists every problem, for example:

Invalid Pinwren configuration:
  - PINWREN_URL: PINWREN_URL must be the public URL, e.g. https://feedback.example.com
  - PINWREN_SECRET: PINWREN_SECRET must be at least 32 characters

Only three variables are required: DATABASE_URL, PINWREN_URL and PINWREN_SECRET. Everything else has a default.

Environment beats the dashboardCopy Anchor Link

Some settings can be edited by an admin in the dashboard and set in the environment — SMTP, the session lifetime and the update check. The rule is the same for all of them:

• The value an admin saves lives in the database.
• A variable set in the environment overrides that value and locks the field: the dashboard shows it as read-only, and saving it is refused with 409 SETTING_LOCKED.
• Remove the variable and restart to hand the setting back to the dashboard.

The Enterprise licence works the same way: with PINWREN_LICENSE_FILE set, the upload in Settings › Licence is locked and refused with 409 LICENSE_LOCKED.

Use the environment for anything you manage as code; use the dashboard for anything you want admins to change without a redeploy.

Client addressesCopy Anchor Link

Rate limits and the sign-in limiter key on the client's IP address. PINWREN_TRUST_PROXY is the number of reverse proxies in front of Pinwren whose X-Forwarded-For entries it believes:

Pinwren walks X-Forwarded-For from the right and skips one entry per trusted hop, so whatever a client writes into the header itself is never taken as its address. X-Real-IP is never read. Set the count to exactly what you run: too low and every client looks like your proxy (one shared rate limit); too high and clients can choose their own address. The details are under Reverse proxy.

Sign-up and instance adminsCopy Anchor Link

• Sign-up. With PINWREN_DISABLE_SIGNUP unset, the first account can always be created and after that only people with a pending invitation can sign up. PINWREN_DISABLE_SIGNUP=false opens sign-up to anyone. PINWREN_DISABLE_SIGNUP=true behaves like unset: the first account and invited people can still sign up.
• Instance admins (SMTP, security, licence and other instance settings) are the first account created on the server, plus every address in PINWREN_ADMIN_EMAILS — see First run. Keep a new server private until that first account exists.

Sign in with Google or GitHubCopy Anchor Link

Both are optional and offered only when configured. Their secrets are read from the environment only, never stored in the database.

1. Create an OAuth app: in Google Cloud (APIs & Services › Credentials › OAuth client ID, type "Web application") or on GitHub (Settings › Developer settings › OAuth Apps).
2. Register the callback URL: PINWREN_URL/api/auth/callback/google or PINWREN_URL/api/auth/callback/github. Settings › Security › Sign-in methods shows both, ready to copy.
3. Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET, or GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET, and restart. Setting only one value of a pair stops the server with a configuration error.

New accounts from Google or GitHub follow the same sign-up rules as a password sign-up (first account, invitations, PINWREN_DISABLE_SIGNUP). Passkeys and email sign-in links need no variables: they are switched in Settings › Security, and email links also need SMTP. Passkeys are bound to the host name in PINWREN_URL, so changing that host means everyone adds their passkeys again.

Outbound requestsCopy Anchor Link

Webhooks, chat channels (Slack, Discord, Teams, Telegram, ntfy), webhook panel actions, the GitHub/GitLab base URL and the Jira site URL an admin enters are URLs typed by users, so Pinwren refuses to send requests to private and internal addresses: loopback, RFC 1918 ranges, CGNAT, link-local and cloud metadata addresses, IPv6 unique-local and link-local, multicast, documentation and reserved ranges — including IPv6 forms that embed one of those IPv4 addresses. Redirects are never followed.

• PINWREN_OUTBOUND_ALLOWLIST admits internal targets, comma- or space-separated: exact host names (gitlab.internal), wildcard subdomains (*.corp.example) and CIDRs (10.20.0.0/16). Use it for a self-managed GitLab, Mattermost or an internal webhook receiver.
• PINWREN_OUTBOUND_ALLOW_PRIVATE=true switches the address check off entirely. It is meant for local development and tests only — never set it on a server people can reach.

GITHUB_API_URL, GITLAB_URL and SLACK_API_URL come from you, not from a user, so they may point at private addresses without the allowlist (timeouts, size caps and no-redirects still apply). SLACK_API_URL (default https://slack.com/api) is the Slack Web API the Slack app calls; change it only for a mock or a proxy.

AI triageCopy Anchor Link

Optional. Set these to configure the AI provider once for the whole instance; an admin can instead choose it under Settings → AI, and what is saved there wins. See AI triage.

Intake and invitation limitsCopy Anchor Link

Cloud billing (Dodo Payments)Copy Anchor Link

Self-hosted installs have no billing: nothing below is read unless PINWREN_MODE=cloud. On Pinwren Cloud the plans (Free and Pro) are sold through Dodo Payments. Billing stays off until DODO_PAYMENTS_API_KEY is set.

An interval whose product id is empty is not offered, and asking for it answers 503 BILLING_NOT_CONFIGURED naming the missing variable. Incoming billing events are checked against the signing secret above (five-minute replay window) and applied once per event id. A workspace is matched to its subscription by the pinwren_org_id metadata set at checkout.

Cloud sign-upCopy Anchor Link

Only read when PINWREN_MODE=cloud. Self-hosted sign-up is still decided by PINWREN_DISABLE_SIGNUP. Cloud sign-up is email and password with a confirmation link, so SMTP must be configured.

Each new account gets a personal workspace on the Free plan and, after it confirms its email address, a guided first run: name the workspace, create the first project, copy the widget snippet and invite teammates (within the plan's seats). Disposable-mailbox domains are refused. Not included yet: CAPTCHA, social sign-up in Cloud, and cleanup of accounts that never confirm.

ReferenceCopy Anchor Link

The table is generated on every build from the Zod schema the server validates its configuration with, packages/api/src/env.ts, plus the few variables read elsewhere (the cluster entry, the database pools and migrations). Boolean variables accept true, false, 1 or 0, except PINWREN_DISABLE_SIGNUP, which takes true or false.

Compose-only variablesCopy Anchor Link

docker/compose.yml reads a few more values from docker/.env to wire the containers together. They are not passed to Pinwren itself.

Besides the three required values, the compose file forwards PINWREN_TRUST_PROXY, PINWREN_DISABLE_SIGNUP, PINWREN_ADMIN_EMAILS, PINWREN_OUTBOUND_ALLOWLIST, PINWREN_WORKERS, PINWREN_LICENSE_FILE, the AI variables and the DODO_* Cloud billing variables from docker/.env. It sets PINWREN_TRUST_PROXY=1 by default, because it expects one reverse proxy in front. Set PINWREN_TRUST_PROXY=0 if clients reach the container directly, and a higher number if there are more proxies — see Client addresses.

Generating secretsCopy Anchor Link

openssl rand -base64 48   # PINWREN_SECRET
openssl rand -hex 24      # POSTGRES_PASSWORD

PINWREN_SECRET signs sessions and derives the AES-256-GCM key that encrypts stored credentials (the SMTP password, webhook signing secrets, tracker tokens). Changing it signs everyone out, and those stored secrets must be entered again.