vynte-infra/plunk
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: expand documentation with new sections on importing contacts, unsubscribe pages, and API key management

Browse Source
This commit is contained in:
Dries Augustyns
2026-05-06 21:37:00 +02:00
parent 88be252a29
commit 4ddafdc041
27 changed files with 1943 additions and 483 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/wiki/content/docs/self-hosting/docker.mdx
+21 -6
View File
@@ -44,12 +44,27 @@ See [Environment Variables](/self-hosting/environment-variables) for all options
## Ports
| Port | Service |
|------|---------|
| 80 | Nginx (HTTP) |
| 465 | SMTP (implicit TLS) |
| 587 | SMTP (STARTTLS) |
| 9000 | Minio API |
| Port | Service |
| ----- | ---------------------------------------- |
| 80 | Nginx (HTTP) — fronts API, dashboard, landing, wiki |
| 465 | SMTP (implicit TLS) |
| 587 | SMTP (STARTTLS) |
| 8080 | API server (proxied through nginx; not usually exposed externally) |
| 9000 | Minio API |
| 9001 | Minio web console |
When deploying behind a reverse proxy or load balancer, expose port 80 (and 465/587 if using SMTP). Postgres, Redis, and Minio are kept internal to the Docker network by default.
## Health check
The API exposes a health endpoint at `/health` for orchestrators (Docker Compose, Kubernetes, load balancers):
```bash
curl https://api.yourdomain.com/health
# { "status": "ok", "time": ..., "uptime": ... }
```
Use this for liveness/readiness probes. It returns `200` when the API process is up and able to serve requests.
## Running Individual Services
apps/wiki/content/docs/self-hosting/email-setup.mdx
+46
View File
@@ -74,3 +74,49 @@ SES_CONFIGURATION_SET_NO_TRACKING="plunk-no-tracking"
Once you have configured AWS SES with the above settings, you can add and verify your domain directly through the Plunk dashboard. Plunk will handle the domain verification and DKIM setup with AWS SES automatically and show you the right records to add to your DNS.
## 6. (Optional) Configure Inbound Email
If you want to use Plunk's [Receiving emails](/guides/receiving-emails) feature, configure SES inbound separately. Plunk does not auto-provision receipt rules, so this is a manual one-time setup in your AWS account.
Not all AWS regions support SES inbound — confirm `inbound-smtp.<your-region>.amazonaws.com` exists for your `AWS_SES_REGION` before continuing. If your region doesn't support inbound, you can keep outbound on your current region and run a separate identity in a region that does.
### Create a receipt rule set
1. SES Console → **Email receiving** → **Rule sets** → Create rule set (or use an existing one)
2. Add a rule:
- **Recipient conditions**: `*@yourdomain.com` (or specific addresses you want to receive)
- **Actions**: Publish to Amazon SNS topic → select your `plunk-ses-events` topic (or create a separate topic that's also subscribed to `https://api.yourdomain.com/webhooks/sns`)
3. Set the rule set as **active**
### Inbound IAM permissions
Plunk doesn't call SES inbound APIs at runtime — the IAM policy from step 1 covers everything Plunk needs. Configuring receipt rules in AWS is a manual one-time action you do as an AWS admin.
### Add an MX record
For each verified domain you want to receive on, add an MX record pointing at the SES inbound endpoint for your region:
```
Type: MX
Name: yourdomain.com
Value: 10 inbound-smtp.<your-region>.amazonaws.com
```
Plunk's dashboard will show the exact value to use for your configured region.
## 7. (Optional) Move Out of the SES Sandbox
By default, new AWS SES accounts are in **sandbox mode** with strict limits:
- Send only to **verified** addresses
- 200 messages per 24 hours
- 1 message per second
Sandbox is fine for testing but useless for production. Request production access in the SES console (**Account dashboard** → **Request production access**) — AWS typically approves within 24 hours after a short questionnaire about your sending practices.
After approval, your sending quota will reflect a much higher daily and per-second limit specific to your account.
## 8. (Optional) Configure a MAIL FROM Domain
For better DMARC alignment, you can configure a custom MAIL FROM subdomain (e.g. `mail.yourdomain.com`). In the SES console under **Verified identities** → your domain → **MAIL FROM domain**, set a subdomain and add the additional MX and TXT records SES displays. Plunk's IAM policy already includes `ses:SetIdentityMailFromDomain` to support this.
apps/wiki/content/docs/self-hosting/environment-variables.mdx
+17 -6
View File
@@ -7,11 +7,13 @@ description: Configuration reference
| 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) |
| `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 used by the application at runtime (typically through PgBouncer). Auto-configured in Docker. | `postgresql://plunk:password@postgres:5432/plunk` |
| `DIRECT_DATABASE_URL` | Yes | Direct PostgreSQL connection string used by Prisma migrations. Must bypass any connection pooler. Auto-configured in Docker. | `postgresql://plunk:password@postgres:5432/plunk` |
| `REDIS_URL` | Yes | Redis connection string. | `redis://redis:6379` |
| `NODE_ENV` | No | Application environment. Set to `production` for production deployments. | `production` |
| `PORT` | No | Port the API server listens on. | `8080` (default) |
## URLs & Domains
@@ -52,6 +54,15 @@ The bundled Docker setup includes Minio with defaults that work out of the box.
| `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` |
## Attachments
Plunk supports attachments on transactional emails. AWS SES caps total message size at 40 MB; the defaults below leave headroom but can be tuned for your use case.
| Variable | Required | Description | Default |
| ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------ | ------- |
| `MAX_ATTACHMENT_SIZE_MB` | No | Maximum total attachment size in megabytes per email. Hard upper bound enforced by AWS SES is 40 MB. | `10` |
| `MAX_ATTACHMENTS_COUNT` | No | Maximum number of attachments per email. | `10` |
## SMTP Server
The optional SMTP relay lets you send emails through Plunk via the SMTP protocol.
@@ -128,7 +139,7 @@ Plunk can use AI to detect and block phishing emails before they're sent. Requir
| `OPENROUTER_API_KEY` | No | OpenRouter API key. When set, enables AI-powered phishing detection. | — |
| `OPENROUTER_MODEL` | No | LLM model to use for content analysis. See [OpenRouter models](https://openrouter.ai/models). | `anthropic/claude-3-haiku` |
| `PHISHING_DETECTION_SAMPLE_RATE` | No | Percentage of emails to check (0.0-1.0). For example, `0.1` means 10% of emails are analyzed. | `0.1` (10%) |
| `PHISHING_CONFIDENCE_THRESHOLD` | No | Minimum confidence percentage (0-100) required to auto-disable a project from a single detection. | `85` |
| `PHISHING_CONFIDENCE_THRESHOLD` | No | Minimum confidence percentage (0-100) required to auto-disable a project from a single detection. | `95` |
| `PHISHING_CUMULATIVE_THRESHOLD` | No | Number of phishing detections within the time window required to auto-disable a project. | `3` |
| `PHISHING_CUMULATIVE_WINDOW_MS` | No | Time window in milliseconds for cumulative phishing tracking. | `3600000` (1 hour) |