diff --git a/CLAUDE.md b/CLAUDE.md index 44acce3..deb33eb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -161,7 +161,7 @@ Required for builds and deployment (see turbo.json and .env.example): - `OPENROUTER_API_KEY` - API key for OpenRouter (enables phishing detection) - `OPENROUTER_MODEL` (default: anthropic/claude-3-haiku) - LLM model to use for content analysis - `PHISHING_DETECTION_SAMPLE_RATE` (default: 0.1) - Percentage of emails to check (0.0-1.0, e.g., 0.1 = 10%) - - `PHISHING_CONFIDENCE_THRESHOLD` (default: 85) - Minimum confidence percentage (0-100) to auto-disable project for single detection + - `PHISHING_CONFIDENCE_THRESHOLD` (default: 95) - Minimum confidence percentage (0-100) to auto-disable project for single detection - `PHISHING_CUMULATIVE_THRESHOLD` (default: 3) - Number of phishing detections within time window to trigger auto-disable - `PHISHING_CUMULATIVE_WINDOW_MS` (default: 3600000) - Time window in milliseconds for cumulative tracking (default 1 hour) @@ -174,6 +174,21 @@ Required for builds and deployment (see turbo.json and .env.example): - **Frontend Variables**: Next.js apps use `NEXT_PUBLIC_*` prefixed variables that are embedded at build time for client-side access +## Environment Variable Changes + +When you add, rename, remove, or change the default/behaviour of any environment variable, you MUST update all THREE of the following in the same change: + +1. `apps/api/.env.example` — local development defaults +2. `.env.self-host.example` — self-hosting / production template +3. `apps/wiki/content/docs/self-hosting/environment-variables.mdx` — user-facing reference + +Rules: + +- If the variable already exists in any file, **modify** its line/row/description — do not duplicate or leave a stale entry. +- Keep section/category names consistent across all three files (e.g. "AWS SES", "Phishing Detection"). +- For dev-only or self-host-only variables, still mention them in the wiki and note the scope; only skip the example file where the variable is genuinely never applicable. +- When in doubt about whether a variable belongs in `apps/api/.env.example` (development), include it commented out with a short note. + ## Plugins There are two plugins installed for you to use. diff --git a/apps/api/.env.example b/apps/api/.env.example index 2d8beb7..eecaf18 100644 --- a/apps/api/.env.example +++ b/apps/api/.env.example @@ -8,6 +8,8 @@ # ============================================================================== NODE_ENV=development JWT_SECRET=hBx9Xh8J6KOMAGAsSjvcZJBT5TWyIkFX +# Port the API server listens on (default: 8080) +# PORT=8080 # ============================================================================== # Application URLs @@ -25,6 +27,8 @@ LANDING_URI=http://localhost:4000 # ============================================================================== # API key for authenticating with the Plunk API (obtained from dashboard) PLUNK_API_KEY= +# From address used for platform notification emails (project disabled, billing limits, etc.) +# PLUNK_FROM_ADDRESS= # ============================================================================== # Database & Redis @@ -85,3 +89,46 @@ STRIPE_METER_EVENT_NAME=emails # Meter event name (API key from your Stripe mete # Set to 'false' to disable automatic project suspension (useful for self-hosters who manage manually) # Default: true (automatic project disabling enabled) # AUTO_PROJECT_DISABLE=true + +# ============================================================================== +# Notifications (Optional - system notifications via ntfy) +# ============================================================================== +# ntfy topic URL for internal system notifications (e.g. project disabled, billing limits). +# When unset, ntfy notifications are disabled. +# Examples: +# - Public ntfy.sh: https://ntfy.sh/your-unique-topic-name +# - Self-hosted: https://your-ntfy-server.com/your-topic +# NTFY_URL= + +# ============================================================================== +# Attachments (Optional) +# ============================================================================== +# Limits applied to attachments on transactional emails. +# AWS SES caps total message size at 40 MB; the defaults below leave headroom. +# MAX_ATTACHMENT_SIZE_MB=10 +# MAX_ATTACHMENTS_COUNT=10 + +# ============================================================================== +# User Management (Optional) +# ============================================================================== +# When 'true', the signup endpoint rejects new user registrations. +# Default: false +# DISABLE_SIGNUPS=false +# When 'true', validates emails on signup (disposable domains, plus-addressing, +# domain existence, MX records). +# Default: false +# VERIFY_EMAIL_ON_SIGNUP=false + +# ============================================================================== +# Phishing Detection (Optional - AI-powered phishing scan via OpenRouter) +# ============================================================================== +# When OPENROUTER_API_KEY is set, a random sample of outgoing emails is +# analyzed by an LLM. Projects can be auto-disabled if a single email exceeds +# PHISHING_CONFIDENCE_THRESHOLD, or if PHISHING_CUMULATIVE_THRESHOLD emails are +# flagged within PHISHING_CUMULATIVE_WINDOW_MS. +# OPENROUTER_API_KEY= +# OPENROUTER_MODEL=anthropic/claude-3-haiku +# PHISHING_DETECTION_SAMPLE_RATE=0.1 +# PHISHING_CONFIDENCE_THRESHOLD=95 +# PHISHING_CUMULATIVE_THRESHOLD=3 +# PHISHING_CUMULATIVE_WINDOW_MS=3600000 diff --git a/apps/wiki/content/docs/self-hosting/environment-variables.mdx b/apps/wiki/content/docs/self-hosting/environment-variables.mdx index 8afe7b0..eeccc95 100644 --- a/apps/wiki/content/docs/self-hosting/environment-variables.mdx +++ b/apps/wiki/content/docs/self-hosting/environment-variables.mdx @@ -36,6 +36,7 @@ Set your subdomains here. The application automatically derives all internal and | `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) | +| `MAIL_FROM_SUBDOMAIN` | No | Subdomain prefix used when constructing the MAIL FROM hostname for a verified domain (e.g. with default `plunk` and domain `yourdomain.com`, the MAIL FROM is `plunk.yourdomain.com`). Override when the default subdomain is already in use (e.g. by an R2/CDN custom domain), since the MAIL FROM hostname needs MX + TXT records that can't coexist with a CNAME. | `plunk` | ## Storage (Minio) @@ -130,6 +131,14 @@ Plunk bundles a self-hosted [ntfy](https://ntfy.sh) server for internal system n | `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. | — | +## Advanced + +Variables for unusual deployments. The defaults work for the standard Docker Compose setup — only change these if you know you need to. + +| Variable | Required | Description | Default | +| ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------ | ------- | +| `NGINX_PORT` | No | Host port the bundled Nginx reverse proxy binds to. Override when port 80/443 is already in use on the host (e.g. running behind another reverse proxy that forwards to a different port). | `80` | + ## Phishing Detection Plunk can use AI to detect and block phishing emails before they're sent. Requires an [OpenRouter](https://openrouter.ai) API key.