How to Self-Host Your Newsletter with Notifuse (2026 Guide)

Notifuse changed enough in the last year that the setup steps from the first version of this guide no longer produce a working install. The current release is v40.0, shipped 5 September 2026. Two things moved: the app now takes a single SECRET_KEY instead of a PASETO key pair, and the bundled Docker Compose file serves the console on port 8081, not 8080. If you copied the old compose file and got a container that started fine but never answered, that’s why.

This is the corrected guide, written for the solo operator with a VPS and somewhere between 2,000 and 50,000 subscribers who wants newsletter and transactional email without per-email pricing. It covers three deployment paths, how to verify each one actually works, day-to-day operations, backups, upgrades that won’t paint you into a corner, and the failures you’ll hit.

One honest framing before any commands: Notifuse is the application layer, not a sending service. You host the app and the database. You still rent deliverability from an email provider. Budget for both.

What Notifuse is (and what it isn’t)

The Docker Hub README puts it plainly: Notifuse is the application layer, not a sending service. It keeps contacts, events and analytics in a Postgres database you control. Mail leaves through your Amazon SES, Mailgun, Postmark, SendGrid, SparkPost, Mailjet or plain SMTP account, at whatever that provider charges per message.

That split is the point. You get the expensive part (contact storage, segmentation, automation, unsubscribe handling) for the price of a small VPS, and you pay commodity rates for the part that genuinely costs money. Amazon SES is around $0.10 per 1,000 emails. Mailchimp charges per contact, dormant ones included.

It’s built in Go with a React console, and it depends on exactly one thing: PostgreSQL 17 or newer. No Redis, no ClickHouse, no Elasticsearch, no worker fleet. That matters more than the feature list when you’re the only person on call, because every extra service is another container in your memory budget and another thing that can die at 2am.

As of September 2026 the image has 100K+ pulls and the repo around 2.2k stars. Not a huge project, but actively released. You’ll see why that cuts both ways in the licence section.

What changed since the first version of this guide

I rewrote this instead of patching it, because six of the old steps were wrong. Here’s the dated changelog, so returning readers can see what moved:

The features that actually matter for a solo operator

The old version of this post listed nine features and told you nothing. Here’s the shorter version.

If you want a smaller surface and no licence questions, Keila is the lighter option: Elixir, Docker, one Postgres, no per-workspace database partitioning.

Licence reality check (read this before you commit)

This is the change that most affects whether you should start.

What applies now: Notifuse v40.0 and every later release ship under the Business Source License 1.1. Each version converts to AGPL-3.0-or-later four years after it ships. v39.x and every earlier release remain AGPL-3.0 permanently; the change isn’t retroactive and can’t be made so. The web analytics SDK stays AGPL in every version.

What you may still do without paying: run Notifuse in production, for a business, at any size. Read, modify and redistribute the source. Host it for other people and charge them for it, which the Additional Use Grant permits explicitly.

The five capabilities that need a licence key:

The first four refuse at the moment you create or change something and answer 402, naming the missing capability. The fifth is quieter: the SSO button stops being offered, the startup log says sso_gated=true, and everyone signs in with a login code. Installing a key brings the button back with no restart.

What an unlicensed install keeps: everything. No telemetry gate, no activation, no account, no phone-home; key verification is offline against a signature compiled into the binary. No workspace, contact, key or setting is deleted, hidden or made read-only. The console never drops into a restricted mode. Permissions already granted stay enforced exactly as granted. SES tenants already provisioned keep sending. The send path contains no licence check of any kind, so scheduled broadcasts, automations and webhooks keep running after a key lapses. An invitation issued while licensed is still accepted afterwards.

Install a key by pasting it in Settings → Licence as root, or by setting NOTIFUSE_LICENSE_KEY (the env var wins, and while it’s set the console refuses to store a competing value). One key covers one deployment, meaning one Postgres database however many API containers you run. A key past expiry keeps granting for a further 30 days.

Sentry, HashiCorp, CockroachDB and Grafana each made the same move at the point their project became something people run in production. For a small shop the practical impact is often zero: most solo operators never create a fourth workspace and never touch template translations or SES tenant isolation. If you do need SSO or a fourth workspace, price the licence against a managed alternative and treat it as a line item. It isn’t a moral question.

Notifuse vs Listmonk, Keila, and the SaaS you’re leaving

Versus SaaS: you stop paying per contact, your data stays put, and you can point the send path at whichever provider is cheapest this year. You also inherit every deliverability problem a Mailchimp used to absorb for you.

Versus Listmonk: Notifuse wins on the visual builder, native multi-tenancy, automations and built-in web analytics. Listmonk wins on size and on having zero licence-key machinery. If the previous section left a bad taste, that’s a legitimate reason to pick Listmonk or Keila.

Versus Keila: the smallest correct answer if you want a newsletter and nothing else. One Postgres, no per-workspace database sprawl. See the self-hosted newsletter with Keila guide for that path.

If you’d rather not run a server at all, EmailOctopus is a cheap hosted email marketing option and MailerLite is a solid hosted newsletter platform. Neither beats self-hosting for someone with 20,000 subscribers and a VPS already paid for. They’re the right answer for someone who doesn’t want to own pg_dump.

Prerequisites

Everything below has to exist before step one. Getting this list wrong is how a 30-minute install turns into an evening.

A €5–8/month EU VPS with 2 vCPU and 2 GB is plenty. Hetzner Cloud is what I’d default to, and it’s worth checking the current Hetzner plans before ordering. Hostinger is the budget alternative. Comparing providers? See DigitalOcean vs Vultr vs Hetzner. On ARM hosts, install Docker and Compose on Ubuntu ARM first.

VPS prices jumped across the board in 2026 — if you’re rethinking a rented box, see what changed and when a mini PC wins.

Which deployment path should you pick?

Three paths, one decision.

Notifuse architecture: reverse proxy and SMTP bridge feed the Notifuse API, which stores data in PostgreSQL 17 with one database per workspace, keeps images in an S3-compatible bucket, and sends mail through your own email provider

One design constraint to internalise now: Notifuse is designed to run as a single instance. Don’t put two app replicas behind a load balancer against one Postgres. You’ll get duplicated webhook deliveries and, since v39.0, a startup refusal the moment one replica migrates the schema and the other restarts. Scale the box, not the replica count.

Option 1: Bundled Docker Compose (fastest path)

This is the official quick start. It clones the repo, builds the image from the included Dockerfile, and starts Postgres alongside it.

1. Install Docker Engine and Compose v2

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

Verify:

docker --version && docker compose version

You want Compose v2 (docker compose, with a space). If docker compose version errors, you have the old v1 binary and every command below will fail. Install the plugin package for your distro and re-check.

2. Clone and start the stack

git clone https://github.com/notifuse/notifuse.git
cd notifuse
docker compose up -d

The first run builds locally, so give it a few minutes. The console is on port 8081:

docker compose ps
curl -I http://localhost:8081

curl should return an HTTP response, either 200 or a redirect to the sign-in page. If it returns nothing, check docker compose logs -f api. The usual cause is Postgres not being healthy yet on a 2 GB box.

3. Create your .env before first launch

Create a .env next to compose.yaml:

SECRET_KEY="$(openssl rand -base64 32)"
DB_PASSWORD="pick-something-long"
ROOT_EMAIL="[email protected]"
API_ENDPOINT="https://newsletter.yourdomain.com"

Run openssl rand -base64 32 yourself and paste the output in quotes. If the stack is already up, docker compose up -d again and it picks the file up. Environment variables always override whatever the setup wizard stored in the database, which is a feature until it’s a surprise.

DB_PASSWORD="mypass#word123"
SECRET_KEY="abc123#xyz789"

4. Complete the setup wizard

Open http://<server-ip>:8081 and work through the wizard:

1. Root administrator email: the account that can create workspaces and reach System Settings.
2. API endpoint: the full public URL, https://newsletter.yourdomain.com, not the IP.
3. SMTP settings: for system mail. Do this now even if you won’t send campaigns for a month. Without it you can’t receive a login or password-reset email.
4. Admin password, or continue with login codes.

5. Put it behind TLS

The app listens on plain HTTP on 8081. Terminate TLS with your proxy and forward to it.

Caddy is the least work. One file at /etc/caddy/Caddyfile:

newsletter.yourdomain.com {
    reverse_proxy 127.0.0.1:8081
}

Then sudo systemctl reload caddy. Caddy gets and renews the Let’s Encrypt certificate on its own. For Traefik labels inside Docker, see Traefik reverse proxy in Docker.

If you’d rather stay on Nginx, the old configuration still works. Change proxy_pass http://localhost:8080; to proxy_pass http://localhost:8081;. That one-line miss is the most common 502 in this article.

6. Verify it’s actually up

docker compose ps
docker compose logs -f api
curl -I https://newsletter.yourdomain.com

What good looks like: both containers Up, log output showing the database migration completing without errors, and a 200 over a valid certificate with no -k flag. Then load the sign-in page and run the wizard’s test email. The full checklist is further down.

Option 2: Deploy with Dokploy

Dokploy is a self-hosted PaaS that gives you a GUI, automatic SSL and a Notifuse template. If you already run it, this is the fastest path.

1. Install Dokploy

curl -sSL https://dokploy.com/install.sh | sh

Full walkthrough in the Dokploy installation guide.

2. Deploy the template

1. Log in to Dokploy and create a new project.
2. Open Templates, search for Notifuse.
3. Fill in the form: your subdomain, SMTP host/port/user/password, admin email.
4. Click Deploy.

Dokploy provisions PostgreSQL 17, wires the networking and issues a Let’s Encrypt certificate.

3. DNS

Add an A record pointing your subdomain at the VPS IP:

4. Verify

Open your domain and log in. If the page 502s, Dokploy is proxying to the wrong port. If TLS fails, the record hasn’t propagated or Let’s Encrypt already rate-limited you from earlier attempts. Check the Dokploy logs before retrying.

Option 3: Standalone container with your own PostgreSQL (production)

The vendor’s production path: the published image against your own Postgres 17. It gives you the cleanest upgrade story and control over where the data lives.

The quick version from Docker Hub:

docker run -d --name notifuse \
  -p 8080:8080 \
  -e DB_HOST=your-postgres-host \
  -e DB_PORT=5432 \
  -e DB_USER=postgres \
  -e DB_PASSWORD=your-password \
  -e SECRET_KEY="$(openssl rand -base64 32)" \
  notifuse/notifuse:latest

For anything you’ll actually run, keep it in Compose. This is the “bring your own Postgres” variant, corrected for v40. The previous version of this guide shipped PASETO_PRIVATE_KEY here, which no longer exists:

services:
  notifuse:
    image: notifuse/notifuse:v40.0
    ports:
      - '8080:8080'
    environment:
      DB_HOST: postgres
      DB_PORT: '5432'
      DB_USER: postgres
      DB_PASSWORD: ${DB_PASSWORD}
      SECRET_KEY: ${SECRET_KEY}
      API_ENDPOINT: https://newsletter.yourdomain.com
      ROOT_EMAIL: [email protected]
      ENVIRONMENT: production
      TELEMETRY: 'false'
      CHECK_FOR_UPDATES: 'false'
    volumes:
      - ./data:/app/data
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped

  postgres:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: postgres
    volumes:
      - postgres-data:/var/lib/postgresql/data
    restart: unless-stopped
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  postgres-data:

Two details make this work, and both are easy to get wrong:

• DB_HOST: postgres, not localhost. Inside a container, localhost is the container. Use the service name, or an external hostname if Postgres lives elsewhere.
• The DB user needs permission to create databases. Notifuse creates one database per workspace plus its own notifuse_system. A user scoped to a single database fails at workspace creation with a permission error.

Environment variables that actually matter

The wizard covers a lot, but production installs should put sensitive values in environment variables, because env vars always override what’s stored in the database.

Required:

Set these for production:

Tuning, worth knowing before you scale:

Only if you need them: SMTP_BRIDGE_*, OIDC_*, TRACING_*, NOTIFUSE_LICENSE_KEY, BROADCAST_DATA_FEED_ALLOW_PRIVATE_HOSTS.

Connect your sending provider (and don’t tank your deliverability)

There are two separate email paths in Notifuse, and conflating them is why people can’t log in.

1. System mail: login links, invitations, password resets. Sent through the SMTP settings from the wizard. Required from day one.
2. Campaign and transactional mail: sent through the ESP you connect to a workspace under its integrations.

For Amazon SES, create SMTP credentials in the SES dashboard’s SMTP settings section. They’re not IAM access keys, and you must request production access before sending to arbitrary addresses. Then add the provider in your workspace, paste the credentials, and send a test.

Getting mail into inboxes is now your job:

• SPF, DKIM and DMARC TXT records on the domain you send from. Skip DKIM and Gmail and Microsoft will punish you within a day.
• A matching From address. Send from [email protected], not a gmail.com address on behalf of yourdomain.com.
• A warmup ramp. Zero to 20,000 sends in one evening on a fresh domain is how you manufacture a reputation problem.
• Bounce and complaint handling. SES suspends accounts for a bad enough complaint rate, and no app-level tuning fixes that.

The SMTP bridge is a different feature. It lets apps that only speak SMTP (Supabase Auth, Firebase, Auth0, cron scripts) relay through Notifuse so they get your MJML templates instead of their default plain text. Disabled by default. Enable with SMTP_BRIDGE_ENABLED=true and pick a TLS posture:

In ENVIRONMENT=production the bridge refuses to start without TLS unless you explicitly set SMTP_BRIDGE_TLS=off. Supplying certs means base64-encoding fullchain.pem and privkey.pem into SMTP_BRIDGE_TLS_CERT_BASE64 and SMTP_BRIDGE_TLS_KEY_BASE64, and after certbot renews you have to re-encode and update the env vars.

Verify the install end to end

Installing is not the same as working. Run this before pointing a real list at it.

curl -X POST https://newsletter.yourdomain.com/api/transactional.send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "your-workspace",
    "notification": {
      "id": "welcome-email",
      "contact": { "email": "[email protected]" },
      "data": { "first_name": "Dragos" }
    }
  }'

If a port check is failing, verify from outside the box with a proper TCP check rather than ping: check remote ports with nc.

Operating it day to day

If the analytics side bothers you, turn it off per workspace or keep site analytics separate. Self-hosted Umami and Plausible both do the job without analytics in your mailing stack.

What it actually costs at 10k subscribers (September 2026)

Assume 10,000 contacts, four sends a month (40,000 emails), and Amazon SES at about $0.10 per 1,000 emails. Order-of-magnitude, not a quote.

Cloud tiers as of September 2026: Lite $16/mo (2,500 active contacts, 1 workspace, 3 team members), Starter $39/mo (10,000 active, 5 workspaces), Pro $99/mo (25,000 active, 10 workspaces, 10 members), Business $249/mo (50,000 active, 20 workspaces, 25 members). Every plan includes every feature and unlimited emails; plans differ only by scale and data retention.

The billing model matters: Cloud charges for active contacts, defined as any unique contact with at least one event in the trailing 30 days (an email sent, a list change, an automation run, a custom event). Dormant contacts don’t count. Mailchimp and Klaviyo bill for the address whether it’s ever opened anything or not. Self-hosting has no per-contact and no per-email fee at all, which is why it’s cheap at 10k and still cheap at 100k.

Backups, updates, and upgrades that won’t break you

This section decides whether self-hosting was a good idea. Read all three parts before touching an upgrade.

Backup and upgrade flow: dump every notifuse database and the data directory, copy offsite, pull a pinned image tag, let the app migrate the schema, then verify. Rollback means restoring the pre-upgrade dump because there is no down-migration

Back up what you can’t re-create

Notifuse creates one database per workspace plus its own system database, so a single pg_dump of notifuse_system is not a backup. If you took the old article’s advice literally, you’ve been backing up configuration and losing contacts.

This loop dumps everything. Run it from the project directory:

#!/usr/bin/env bash
# Back up every Notifuse database plus the ./data mount.
set -euo pipefail

STAMP=$(date +%F-%H%M)
OUT="/srv/backups/notifuse/$STAMP"
mkdir -p "$OUT"

DBS=$(docker compose exec -T postgres psql -U postgres -Atc \
  "SELECT datname FROM pg_database
   WHERE datname LIKE 'notifuse%' AND datistemplate = false;")

for db in $DBS; do
  docker compose exec -T postgres pg_dump -U postgres -Fc "$db" > "$OUT/$db.dump"
done

tar czf "$OUT/data-dir.tar.gz" -C "$HOME/notifuse/data" .
echo "backed up: $DBS"

The ./data bind mount holds the GeoLite2 database and any locally mounted assets, which is why it’s in the same archive. Then copy the directory offsite. Bunny Storage for offsite backups and email image assets covers both jobs at once. A backup on the same disk as the database is a copy, not a backup. For config-driven versions, Dokploy backups with Cloudflare R2 and Restic-based backups are both solid.

Do the restore drill. It’s the only proof the backup works:

docker compose exec -T postgres createdb -U postgres notifuse_restore_test
docker compose exec -T postgres pg_restore -U postgres -d notifuse_restore_test < /srv/backups/notifuse/2026-09-14-0300/notifuse_system.dump
docker compose exec -T postgres psql -U postgres -d notifuse_restore_test -c "SELECT count(*) FROM contacts;"
docker compose exec -T postgres dropdb -U postgres notifuse_restore_test

If the count matches your contact list, you have a restore path. If pg_restore errors on a missing role or extension, better now than during an incident.

Update the app

1. Pin your image tag in the compose file (notifuse/notifuse:v40.0).
2. Run the backup above.
3. Read the release notes for the target version, paying attention to licence and feature changes.
4. Pull and restart:

docker compose pull
docker compose up -d

On Dokploy, Redeploy does the same thing, and updating the stack in Dokploy covers the GUI path. The generic case is updating a container with Docker Compose.

Then verify: docker compose ps, migration finished in the logs, log in, send yourself a test email. A successful pull proves nothing on its own.

The upgrade traps (read before you pull)

There is no down-migration. The app migrates the schema forward and nothing moves it back.

Since v39.0, Notifuse refuses to start when its database was migrated by a newer build. The startup log names both versions and the two ways out: deploy a build at least as new as the database, or restore a database stamped no higher. Two consequences:

• A rolling deploy has to replace every replica before the first one migrates, because an older replica restarting afterwards will never come back up. Another reason not to run multiple app replicas.
• Rolling back to a previous image requires a database from before the upgrade. Stop the app, restore the pre-upgrade dump, then start the older image.

Upgrading Postgres itself is a separate project. The shipped compose file deliberately stays on Postgres 17, because moving to 18 needs pg_upgrade and 18 changed its data directory layout. That’s a Postgres problem, not a Notifuse one, and it deserves its own maintenance window.

An expired or removed licence key doesn’t stop sending. It greys out the five gated capabilities and leaves the send path untouched.

Troubleshooting: the failures you’ll actually hit

If a port looks open locally but isn’t reachable from outside, check whether Docker is bypassing your firewall rules: Docker bypasses UFW explains the iptables behaviour and the fix.

Hardening and production notes

Short list, all of it load-bearing.

When self-hosting Notifuse is the wrong call

Three cases where I’d tell you not to bother.

Your list is tiny and not growing. Under a few hundred subscribers, a hosted free tier is less work than any self-hosted option, and per-contact pricing hasn’t started to bite. Use a free plan and revisit this in a year.

You have no appetite for DNS, deliverability or pg_dump. Notifuse Cloud runs the same software from $16/month. If you’d rather not own a Postgres backup routine or debug DKIM records, paying someone is rational, not a capitulation. Self-hosting is only cheaper if your time is free.

You need a fourth workspace or SSO and won’t buy a key. Then pick Keila or Listmonk, neither of which has a licence-key concept. Running software whose licence terms you resent is a bad foundation for a business process.

If you land in the first or second bucket, MailerLite is a solid hosted newsletter platform and Sender has a free-forever plan worth pricing against your list size.

FAQ

Key takeaways

Want to see it before installing? The vendor’s live demo runs the full console, and the self-hosting docs are the primary source for every environment variable here. Still deciding on the platform? Start with the Dokploy installation guide; it pays for itself the second time you deploy something.