Skip to main content
Looking for a managed solution? Notifuse Cloud takes care of hosting, security, backups, updates, and maintenance for you — starting from $16/month.

Getting started

Notifuse includes an interactive Setup Wizard that makes installation easy. Many environment variables are optional and can be configured through the web interface on first launch. Setup Wizard

Quick Start with Setup Wizard

  1. Deploy Notifuse using one of the options below
  2. Access your instance in a web browser
  3. Complete the Setup Wizard:
    • Enter your root administrator email
    • Configure your API endpoint
    • Set up SMTP settings
  4. Start using Notifuse!
This option includes an embedded PostgreSQL database for easy testing and development:
These steps set up a new installation. To upgrade one that already runs, keep the SECRET_KEY it runs with and skip the key step: a new key on its own leaves your stored data unreadable. An installation that started from compose.yaml before version 42.0 without setting SECRET_KEY runs on a default that Notifuse now refuses: Replacing the secret key gives it, and the change to make.
This will start Notifuse on port 8081 with a PostgreSQL database. On first launch, you’ll be guided through the Setup Wizard to configure your instance. Alternatively, you can configure environment variables in a .env file or directly in the compose.yaml.

Option 2: Standalone Docker (Production)

For production deployments, use the standalone Docker image with your own PostgreSQL database:
On first launch, you’ll be guided through the Setup Wizard to configure your instance. Alternatively, you can configure environment variables. Note: You’ll need to provide your own PostgreSQL database.

PostgreSQL database (Option 2 only)

If using the standalone Docker option, you can use any PostgreSQL database with root credentials. Notifuse automatically creates a system database for itself. Recommended version: PostgreSQL 17 or higher A new database will be created for each Notifuse workspace to avoid multi-tenant issues (that’s why you need root credentials). Note: This is not required when using Docker Compose as PostgreSQL is included.

An SMTP server

Notifuse needs an SMTP server to send system emails (e.g. password reset emails, invitation emails, etc.). If using SES, you can create SMTP credentials in the SMTP settings section of the SES dashboard.

A public API endpoint

Notifuse needs a public API endpoint to be accessible from the web. Example: https://emails.yourcompany.com

Environment Variables

With the Setup Wizard, many environment variables are optional and can be configured through the web interface. Environment variables always take precedence over database settings when present.
Special Characters in .env FilesIf you’re using a .env file and any of your values contain the # character (common in passwords), you must wrap the value in quotes:
This limitation only applies to .env files. Environment variables set directly in your shell, Docker Compose, or container orchestration platform do not have this restriction.

Required Variables

Generate SECRET_KEY:
Notifuse refuses to start with a SECRET_KEY that gives less than 32 bytes.
IMPORTANT: Never replace your SECRET_KEY with a new value on its own. It encrypts all workspace integration secrets (email provider API keys, SMTP passwords, etc.), which a new key alone cannot read. To change it, follow Replacing the secret key.

Replacing the secret key

SECRET_KEY can list several keys separated by commas (a comma that is part of a key is written twice). The first key encrypts and signs; the others only let Notifuse read the data stored under them. When Notifuse starts with a list, it re-encrypts that data with the first key, in a single transaction, before serving anything. To replace your key:
  1. Generate a new key with openssl rand -base64 32.
  2. Put it first and your current key after it: SECRET_KEY=<new key>,<current key>. If your current key contains a comma, write that comma twice, and if it starts or ends with one, put a space between it and the comma that separates the keys (SECRET_KEY=<new key>, ,,<rest of the key>). A version before 42.0 reads the whole list as a single key: when you upgrade to 42.0, set the list in the same step.
  3. Stop every Notifuse instance, then start them all with that value. An instance still running with the current key alone cannot read the data the others re-encrypted, and an instance running the list cannot read what such an instance writes until the next start with the list.
  4. Once every instance runs with that value, set SECRET_KEY to the new key alone, without quotes or spaces around it: a single key is used exactly as written. If it opens none of the stored workspaces (or, while none is stored, none of the encrypted system settings), Notifuse does not start.
If the key of a workspace, or a credential it uses, opens with none of the listed keys, Notifuse does not start, changes nothing, and names that workspace. An encrypted system setting that none of them opens (an SMTP credential or the OIDC client secret saved in the setup wizard, the SMTP bridge TLS certificate or key) is left as it is and named in a warning in the startup logs, and Notifuse runs without it: to keep it, list the key it is encrypted with. Notifuse does not start, and names the setting, when single sign-on or the SMTP bridge is on and needs it, or when no workspace is stored yet and none of those settings opens. Replacing the key signs everyone out. API keys must be deleted and created again, pending invitations must be sent again, and scripts that call user.rootSignin sign with the new key. An API client that saves an integration with the encrypted credentials it read before the change is refused until it reads the workspace again. Database backups taken before the change still need the former key. Data kept in each workspace’s database, such as message history, is encrypted with that workspace’s own key and is not affected.
Before version 42.0, compose.yaml provided a default SECRET_KEY and env.example a placeholder. Notifuse refuses to start when the first key of SECRET_KEY is one of those values or gives less than 32 bytes, and reads a single comma as a separator between keys: if your key contains a comma, write each of its commas twice when you upgrade. If your installation runs with one of those values, replace it as above, keeping it after the new key, in the same step as the upgrade to 42.0. If you started from compose.yaml without setting SECRET_KEY, your current key is the former default:

Application Variables (Optional with Setup Wizard)

These variables can be configured via the Setup Wizard on first launch, or set as environment variables. Environment variables always override wizard settings.
Multiple root users: ROOT_EMAIL can hold more than one email (comma/semicolon-separated), so a shared instance can have several administrators with root privileges — creating workspaces, accessing System Settings, and authenticating programmatically. A user account is created for each listed email on startup, so every root can sign in immediately. Matching is case-sensitive, and a single email behaves exactly as before. The Setup Wizard establishes the first (primary) root; additional roots can be added there as a list or via the ROOT_EMAIL environment variable.

Optional Variables

SMTP Bridge Configuration

The SMTP Bridge feature allows you to connect SaaS applications that only provide SMTP integration (like Supabase Auth, Firebase, Auth0, etc.) to Notifuse. This gives you full control over email designs and branding using Notifuse’s MJML editor, instead of being stuck with default SaaS templates. See SMTP Bridge usage documentation for examples of how to send emails once configured.

TLS Modes

The bridge supports three TLS postures via SMTP_BRIDGE_TLS: When SMTP_BRIDGE_TLS is unset, Notifuse picks starttls if both cert and key are provided, otherwise off in development.
In production (ENVIRONMENT=production), the bridge refuses to start without TLS configured. You must either provide SMTP_BRIDGE_TLS_CERT_BASE64 and SMTP_BRIDGE_TLS_KEY_BASE64, or explicitly set SMTP_BRIDGE_TLS=off if you’re running behind a TLS-terminating reverse proxy.

Production Setup with Let’s Encrypt

For production deployments, use valid TLS certificates from Let’s Encrypt using certbot with DNS challenges.

Step 1: Install Certbot

Step 2: Generate Certificate with DNS Challenge

DNS challenge is recommended because it doesn’t require opening port 80 or 443, and works even if your SMTP server is on a different port.
When prompted, certbot will ask you to create a DNS TXT record:

Step 3: Add DNS TXT Record

Add the TXT record to your DNS provider:
Wait a few minutes for DNS propagation, verify with:
Press Enter in certbot to continue once the record is verified.

Step 4: Encode Certificates to Base64

After certbot successfully generates the certificates, encode them to base64:

Step 5: Add to Environment Variables

Copy the base64-encoded values to your .env file:
Certbot automatically sets up a renewal cron job. After certificate renewal, you’ll need to re-encode the certificates to base64 and update your environment variables.

Development Setup with Self-Signed Certificates

For local development, you can use self-signed certificates:
⚠️ Warning: Self-signed certificates are for development only. Never use them in production!

Configuration Management

Setup Wizard vs Environment Variables
  • Setup Wizard: Ideal for quick deployments and testing. Configuration is stored securely in the database and can be managed through the web interface.
  • Environment Variables: Recommended for production deployments. Provides better security for sensitive data and allows configuration management through your deployment pipeline.
  • Priority: Environment variables always take precedence over database settings when both are present.
For Production Deployments: We recommend using environment variables for sensitive configuration (SMTP credentials, SECRET_KEY) and the Setup Wizard or admin interface for non-sensitive settings (API endpoint, etc.).

Programmatic Authentication

For CI/CD pipelines and automated deployments, a root user can authenticate programmatically using HMAC-SHA256 signature, bypassing magic link authentication. When ROOT_EMAIL lists multiple addresses, use any one of them as ROOT_EMAIL below — the signed email must exactly match one of the configured root emails.
The endpoint returns a JWT token for subsequent API requests. Timestamps must be within 60 seconds of server time, and requests are rate limited to 5 attempts per 5 minutes.

Third-party Hosting Platforms

Notifuse is also available on the following third-party platforms.
These platforms are not officially supported and often run outdated versions of Notifuse. For the latest version, automatic updates, and official support, use Notifuse Cloud.