From f0ef34646e7593f07a780141e14d6d2b735c1101 Mon Sep 17 00:00:00 2001 From: Dries Augustyns Date: Thu, 12 Mar 2026 17:24:37 +0100 Subject: [PATCH] docs: Improve self-hosting env variable documentation --- .../self-hosting/environment-variables.mdx | 148 ++++++++++++------ 1 file changed, 101 insertions(+), 47 deletions(-) diff --git a/apps/wiki/content/docs/self-hosting/environment-variables.mdx b/apps/wiki/content/docs/self-hosting/environment-variables.mdx index d90fe4c..9e9ce2b 100644 --- a/apps/wiki/content/docs/self-hosting/environment-variables.mdx +++ b/apps/wiki/content/docs/self-hosting/environment-variables.mdx @@ -3,64 +3,118 @@ title: Environment Variables description: Configuration reference --- -## Required +## Security & Database -```bash -# Security -JWT_SECRET="your-secret" # openssl rand -base64 32 -DB_PASSWORD="your-password" +| Variable | Required | Description | Example | +|---|---|---|---| +| `JWT_SECRET` | Yes | Secret key used to sign JWT tokens. Generate with `openssl rand -base64 32`. | `s3cr3t...` | +| `DB_PASSWORD` | Yes | PostgreSQL database password. Used by the Docker Compose setup. | `changeme123` | +| `DATABASE_URL` | Yes | Full PostgreSQL connection string. Auto-configured in Docker. | `postgresql://plunk:password@postgres:5432/plunk` | +| `REDIS_URL` | Yes | Redis connection string. | `redis://redis:6379` | +| `PORT` | No | Port the API server listens on. | `8080` (default) | -# Database (auto-configured in Docker) -DATABASE_URL="postgresql://plunk:password@postgres:5432/plunk" -REDIS_URL="redis://redis:6379" +## URLs & Domains -# AWS SES -AWS_SES_REGION="us-east-1" -AWS_SES_ACCESS_KEY_ID="your-key" -AWS_SES_SECRET_ACCESS_KEY="your-secret" -SES_CONFIGURATION_SET="plunk-tracking" -``` +Set your subdomains here. The application automatically derives all internal and client-side URLs from these at container startup — you don't need to set `*_URI` or `NEXT_PUBLIC_*` variables manually. -## Domains +| Variable | Required | Description | Example | +|---|---|---|---| +| `API_DOMAIN` | Yes | Subdomain for the API server. | `api.yourdomain.com` | +| `DASHBOARD_DOMAIN` | Yes | Subdomain for the dashboard app. | `app.yourdomain.com` | +| `LANDING_DOMAIN` | Yes | Subdomain for the landing page. | `www.yourdomain.com` | +| `WIKI_DOMAIN` | Yes | Subdomain for the documentation site. | `docs.yourdomain.com` | +| `USE_HTTPS` | No | Set to `true` when running behind a TLS-terminating reverse proxy. Used to construct URLs with the correct protocol. | `false` (default) | -```bash -# Subdomains for routing -API_DOMAIN="api.yourdomain.com" -DASHBOARD_DOMAIN="app.yourdomain.com" -LANDING_DOMAIN="www.yourdomain.com" -WIKI_DOMAIN="docs.yourdomain.com" -SMTP_DOMAIN="smtp.yourdomain.com" +## AWS SES -# Protocol -USE_HTTPS="true" # false for local dev -``` +| Variable | Required | Description | Example | +|---|---|---|---| +| `AWS_SES_REGION` | Yes | AWS region where SES is configured. | `us-east-1` | +| `AWS_SES_ACCESS_KEY_ID` | Yes | AWS access key ID with SES send permissions. | `AKIA...` | +| `AWS_SES_SECRET_ACCESS_KEY` | Yes | AWS secret access key for SES. | `wJalr...` | +| `SES_CONFIGURATION_SET` | No | SES configuration set name used for open/click tracking. | `plunk-configuration-set` (default) | +| `SES_CONFIGURATION_SET_NO_TRACKING` | No | A second SES configuration set without tracking. When set, projects can toggle email tracking on/off. If omitted, the tracking toggle is hidden. | `plunk-no-tracking-configuration-set` (default) | ## Storage (Minio) -Defaults work with bundled Minio. Only set for external S3: +The bundled Docker setup includes Minio with defaults that work out of the box. Only change these when connecting to an external S3-compatible bucket. -```bash -S3_ENDPOINT="http://minio:9000" -S3_ACCESS_KEY_ID="plunk" -S3_ACCESS_KEY_SECRET="plunkminiopass" -S3_BUCKET="uploads" -S3_PUBLIC_URL="http://localhost:9000/uploads" -S3_FORCE_PATH_STYLE="true" -``` +| Variable | Required | Description | Default | +|---|---|---|---| +| `MINIO_ROOT_USER` | No | Minio root username (Docker Compose only). | `plunk` | +| `MINIO_ROOT_PASSWORD` | No | Minio root password (Docker Compose only). | `plunkminiopass` | +| `MINIO_API_PORT` | No | Port for the Minio API (Docker Compose only). | `9000` | +| `MINIO_CONSOLE_PORT` | No | Port for the Minio console UI (Docker Compose only). | `9001` | +| `S3_ENDPOINT` | No | S3 or Minio endpoint URL. | `http://minio:9000` | +| `S3_ACCESS_KEY_ID` | No | S3 or Minio access key. | — | +| `S3_ACCESS_KEY_SECRET` | No | S3 or Minio secret key. | — | +| `S3_BUCKET` | No | Bucket name for file uploads. | `uploads` | +| `S3_PUBLIC_URL` | No | Publicly accessible base URL for stored files. | — | +| `S3_FORCE_PATH_STYLE` | No | Use path-style URLs instead of virtual-hosted. Required for Minio. | `true` | -## Optional +## SMTP Server -```bash -# OAuth -GITHUB_OAUTH_CLIENT="client-id" -GITHUB_OAUTH_SECRET="client-secret" -GOOGLE_OAUTH_CLIENT="client-id" -GOOGLE_OAUTH_SECRET="client-secret" +The optional SMTP relay lets you send emails through Plunk via the SMTP protocol. -# Stripe -STRIPE_SK="sk_..." -STRIPE_WEBHOOK_SECRET="whsec_..." +| Variable | Required | Description | Default | +|---|---|---|---| +| `SMTP_DOMAIN` | No | SMTP relay domain. Required when using Traefik's `acme.json` with multiple certificates so the correct cert can be selected. | `localhost` | +| `SMTP_ENABLED` | No | Explicitly enable SMTP features in the UI. Automatically enabled when `SMTP_DOMAIN` is set to a non-localhost value in production. | `false` | +| `PORT_SECURE` | No | SMTPS port (implicit TLS). | `465` | +| `PORT_SUBMISSION` | No | SMTP submission port (STARTTLS). | `587` | +| `MAX_RECIPIENTS` | No | Maximum number of recipients per email. | `5` | -# Notifications -NTFY_URL="http://ntfy/plunk-notifications" -``` +## OAuth + +Enables social login. Register an OAuth app with each provider and add the credentials here. + +| Variable | Required | Description | +|---|---|---| +| `GITHUB_OAUTH_CLIENT` | No | GitHub OAuth app client ID. | +| `GITHUB_OAUTH_SECRET` | No | GitHub OAuth app client secret. | +| `GOOGLE_OAUTH_CLIENT` | No | Google OAuth app client ID. | +| `GOOGLE_OAUTH_SECRET` | No | Google OAuth app client secret. | + +## Stripe + +Required if you want to enable billing features. All Stripe variables must be set together for billing to activate. + +| Variable | Required | Description | +|---|---|---| +| `STRIPE_SK` | No | Stripe secret key. | +| `STRIPE_WEBHOOK_SECRET` | No | Stripe webhook signing secret for verifying events. | +| `STRIPE_PRICE_ONBOARDING` | No | Stripe price ID for the one-time onboarding fee. | +| `STRIPE_PRICE_EMAIL_USAGE` | No | Stripe price ID for metered pay-per-email usage. | +| `STRIPE_METER_EVENT_NAME` | No | Stripe meter event name. | `emails` (default) | + +## Platform Emails + +When configured, Plunk will send email notifications to users for critical events (e.g. project disabled, billing limits reached). Without these, only ntfy notifications are sent. + +| Variable | Required | Description | Example | +|---|---|---|---| +| `PLUNK_API_KEY` | No | API key for a Plunk instance to send transactional emails. | `pk_...` | +| `PLUNK_FROM_ADDRESS` | No | From address used for platform notification emails. | `noreply@yourdomain.com` | + +## Notifications (ntfy) + +Plunk bundles a self-hosted [ntfy](https://ntfy.sh) server for internal system notifications. + +| Variable | Required | Description | Default | +|---|---|---|---| +| `NTFY_PORT` | No | Port for the ntfy web UI (Docker Compose only). | `8080` | +| `NTFY_URL` | No | ntfy topic URL. Change this to use an external ntfy.sh server or your own instance. | `http://ntfy/plunk-notifications` | + +## User Management + +| Variable | Required | Description | Default | +|---|---|---|---| +| `DISABLE_SIGNUPS` | No | When `true`, the signup endpoint rejects new registrations. Useful for private instances. | `false` | +| `VERIFY_EMAIL_ON_SIGNUP` | No | When `true`, validates emails on signup — checks for disposable domains, plus-addressing, domain existence, and MX records. | `false` | + +## Security + +| Variable | Required | Description | Default | +|---|---|---|---| +| `AUTO_PROJECT_DISABLE` | No | When `true`, projects are automatically suspended when bounce or complaint rate thresholds are exceeded. Set to `false` to manage project status manually. | `true` | +| `EMAIL_RATE_LIMIT_PER_SECOND` | No | Override the email sending rate limit. If not set, Plunk automatically fetches the quota from your AWS SES account. | — |