Skip to main content
Self-hosting Plunk means you run the entire platform — the API, dashboard, email worker, database, file storage, and notification server — on your own servers. You bring your own AWS SES account for email delivery. Everything else is bundled in a single Docker image.

​
Requirements

Before you start, make sure you have the following:
  • Docker and Docker Compose installed on your server
  • An AWS account with SES available in your target region
  • A domain name with DNS control, so you can create the required subdomains

​
Quick start

1

Download docker-compose.yml

Fetch the official Compose file directly from GitHub:
curl -O https://raw.githubusercontent.com/useplunk/plunk/next/docker-compose.yml
2

Configure environment variables

Copy the example env file and fill in your values:
curl -O https://raw.githubusercontent.com/useplunk/plunk/next/.env.self-host.example
cp .env.self-host.example .env
At minimum you need to set:
JWT_SECRET="$(openssl rand -base64 32)"
DB_PASSWORD="your-secure-password"

API_DOMAIN="api.yourdomain.com"
DASHBOARD_DOMAIN="app.yourdomain.com"
USE_HTTPS="true"

AWS_SES_REGION="us-east-1"
AWS_SES_ACCESS_KEY_ID="AKIA..."
AWS_SES_SECRET_ACCESS_KEY="..."
SES_CONFIGURATION_SET="plunk-tracking"
See Environment variables for the full reference.
3

Start the stack

docker compose up -d
The stack starts PostgreSQL and Redis first, waits for their health checks to pass, then starts the Plunk application container. Database migrations run automatically on startup.

​
Domain setup

Plunk uses subdomain-based routing. Create DNS A records (or CNAME records if behind a load balancer) for each subdomain pointing to your server’s IP address.
SubdomainServiceRequired
api.yourdomain.comAPI serverYes
app.yourdomain.comDashboardYes
www.yourdomain.comLanding pageNo
docs.yourdomain.comDocumentation siteNo
smtp.yourdomain.comSMTP relayNo
You need a reverse proxy (Traefik, nginx, Caddy) in front of the Plunk container to terminate TLS and route subdomains. The container’s nginx listens on port 80 and routes by Host header internally. Point your reverse proxy at port 80 of the plunk container.

​
Services in the stack

The Docker Compose file runs five containers:
ContainerImagePurpose
plunkghcr.io/useplunk/plunk:latestAll application services: API server, BullMQ worker, Next.js dashboard, landing page, documentation site, and optional SMTP relay — all managed by PM2 behind nginx
postgrespostgres:16-alpinePrimary database
redisredis:7-alpineQueue backend for BullMQ email and workflow jobs
miniominio/minio:latestS3-compatible file storage for uploads
ntfybinwiederhier/ntfy:latestInternal system notifications

​
Next steps

Docker deployment

Understand the container internals, runtime environment injection, SMTP TLS setup, and how to upgrade.

Environment variables

Complete reference for every configuration variable, organized by category.

Email setup

Step-by-step AWS SES configuration: IAM credentials, configuration sets, SNS topics, and bounce handling.

API reference

Explore the REST API once your instance is running.

Build docs developers (and LLMs) love

Get started for freeTalk to us