Skip to main content

​
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!

​
One-click Deployments

Deploy Notifuse instantly with these one-click deployment options: Deploy on Railway Run on PikaPods These deployment platforms will automatically set up Notifuse with all required dependencies. After deployment, you’ll be guided through the Setup Wizard to complete your configuration.
You also have the following options to deploy Notifuse: This option includes an embedded PostgreSQL database for easy testing and development: 
# Clone the repository or download compose.yaml
curl -O https://raw.githubusercontent.com/notifuse/notifuse/main/compose.yaml

# Start Notifuse with embedded PostgreSQL
docker compose up -d
This will start Notifuse on port 8080 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: 
docker run -d --name notifuse -p 8080:8080 notifuse/notifuse:latest
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:
# ✅ CORRECT - value is quoted
DB_PASSWORD="mypass#word123"
SECRET_KEY="abc123#xyz789"

# ❌ INCORRECT - will be truncated at the # character
DB_PASSWORD=mypass#word123   # parsed as "mypass"
SECRET_KEY=abc123#xyz789     # parsed as "abc123"
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

VariableDescription
DB_HOSTPostgreSQL host (e.g., localhost or db.yourcompany.com)
DB_PORTPostgreSQL port (e.g., 5432)
DB_USERDatabase username (e.g., postgres)
DB_PASSWORDDatabase password (e.g., postgres)
SECRET_KEYSecret key for encryption (generate with command below)
Generate SECRET_KEY: 
openssl rand -base64 32
IMPORTANT: Never change your SECRET_KEY after initial setup. It encrypts all workspace integration secrets (email provider API keys, SMTP passwords, etc.). Changing it will permanently destroy all encrypted credentials.

​
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.
VariableDescription
ROOT_EMAILRoot administrator email (e.g., admin@yourcompany.com)
API_ENDPOINTPublic API endpoint URL (e.g., https://emails.yourcompany.com)
SMTP_HOSTSMTP server host (e.g., smtp.gmail.com)
SMTP_PORTSMTP server port (e.g., 587 or 465)
SMTP_USERNAMESMTP username (e.g., noreply@yourcompany.com)
SMTP_PASSWORDSMTP password (e.g., your_smtp_password)
SMTP_FROM_EMAILFrom email address (e.g., noreply@yourcompany.com)
SMTP_FROM_NAMEFrom name (e.g., Your Company Name)

​
Optional Variables

VariableDescriptionDefault
Server Configuration
SERVER_PORTPort for the server to listen on (e.g., 8080)8080
SERVER_HOSTHost address to bind to (e.g., 0.0.0.0)0.0.0.0
CORS_ALLOW_ORIGINCORS allowed origins (e.g., https://yourapp.com,https://admin.yourapp.com)*
ENVIRONMENTEnvironment mode (e.g., production)production
LOG_LEVELLogging level (e.g., debug or warn)info
Database Configuration
DB_PREFIXDatabase table prefix (e.g., notifuse)notifuse
DB_NAMEDatabase name (e.g., notifuse_system)${DB_PREFIX}_system
DB_SSLMODESSL mode for database (e.g., require or disable)require
DB_MAX_CONNECTIONSTotal max connections across all databases (e.g., 100)100
DB_MAX_CONNECTIONS_PER_DBMax connections per workspace database (e.g., 3)3
DB_CONNECTION_MAX_LIFETIMEMaximum lifetime of a connection (e.g., 10m)10m
DB_CONNECTION_MAX_IDLE_TIMEMaximum idle time before closing connection (e.g., 5m)5m
Task Scheduler Configuration
TASK_SCHEDULER_ENABLEDEnable internal task scheduler (e.g., true or false)true
TASK_SCHEDULER_INTERVALTask execution interval in seconds (e.g., 30)30
TASK_SCHEDULER_MAX_TASKSMaximum concurrent tasks (e.g., 10)10
Privacy Settings
TELEMETRYSend anonymous usage statistics (e.g., true or false)true
CHECK_FOR_UPDATESCheck for new versions (e.g., true or false)true
SMTP Relay Configuration
SMTP_RELAY_ENABLEDEnable SMTP relay server for transactional emails (e.g., true or false)false
SMTP_RELAY_PORTSMTP relay port (e.g., 587 for STARTTLS)587
SMTP_RELAY_DOMAINPublic domain name for SMTP relay (e.g., smtp.yourdomain.com)localhost
SMTP_RELAY_TLS_CERT_BASE64Base64-encoded TLS certificate for SMTP relay-
SMTP_RELAY_TLS_KEY_BASE64Base64-encoded TLS private key for SMTP relay-
Tracing Configuration
TRACING_ENABLEDEnable tracing (e.g., true)false
TRACING_SERVICE_NAMEService name for tracing (e.g., notifuse-production)notifuse-api
TRACING_SAMPLING_PROBABILITYSampling probability (e.g., 0.05)0.1
TRACING_TRACE_EXPORTERTrace exporter: jaeger/zipkin/stackdriver/datadog/xray/none (e.g., jaeger or datadog)none
TRACING_JAEGER_ENDPOINTJaeger endpoint (e.g., http://jaeger:14268/api/traces)http://localhost:14268/api/traces
TRACING_ZIPKIN_ENDPOINTZipkin endpoint (e.g., http://zipkin:9411/api/v2/spans)http://localhost:9411/api/v2/spans
TRACING_STACKDRIVER_PROJECT_IDStackdriver project ID (e.g., my-gcp-project-id)-
TRACING_AZURE_INSTRUMENTATION_KEYAzure Monitor instrumentation key (e.g., 12345678-1234-1234-1234-123456789012)-
TRACING_DATADOG_AGENT_ADDRESSDatadog agent address (e.g., datadog-agent:8126)localhost:8126
TRACING_DATADOG_API_KEYDatadog API key (e.g., 1234567890abcdef1234567890abcdef)-
TRACING_XRAY_REGIONAWS X-Ray region (e.g., us-east-1)us-west-2
TRACING_AGENT_ENDPOINTGeneral agent endpoint (e.g., monitoring-agent:8126)localhost:8126
TRACING_METRICS_EXPORTERMetrics exporter: stackdriver/prometheus/datadog/none (e.g., prometheus)none
TRACING_PROMETHEUS_PORTPrometheus metrics port (e.g., 9464)9464

​
SMTP Relay Configuration

The SMTP Relay 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 Relay usage documentation for examples of how to send emails once configured.

​
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

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install certbot

# macOS
brew install certbot

# CentOS/RHEL
sudo yum 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. 
# Generate certificate using DNS challenge
sudo certbot certonly \
  --manual \
  --preferred-challenges dns \
  --email admin@yourdomain.com \
  --agree-tos \
  -d smtp.yourdomain.com
When prompted, certbot will ask you to create a DNS TXT record: 
Please deploy a DNS TXT record under the name
_acme-challenge.smtp.yourdomain.com with the following value:

XyZ123AbC456...

Before continuing, verify the record is deployed by running:
dig -t txt _acme-challenge.smtp.yourdomain.com

​
Step 3: Add DNS TXT Record

Add the TXT record to your DNS provider: 
Type: TXT
Name: _acme-challenge.smtp
Value: XyZ123AbC456... (the value provided by certbot)
TTL: 300 (5 minutes)
Wait a few minutes for DNS propagation, verify with: 
dig -t txt _acme-challenge.smtp.yourdomain.com

# Or using nslookup
nslookup -type=TXT _acme-challenge.smtp.yourdomain.com
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: 
# Certificate location (typically):
# Certificate: /etc/letsencrypt/live/smtp.yourdomain.com/fullchain.pem
# Private Key: /etc/letsencrypt/live/smtp.yourdomain.com/privkey.pem

# Encode certificate to base64 (single line)
sudo cat /etc/letsencrypt/live/smtp.yourdomain.com/fullchain.pem | base64 -w 0 > cert_base64.txt

# Encode private key to base64 (single line)
sudo cat /etc/letsencrypt/live/smtp.yourdomain.com/privkey.pem | base64 -w 0 > key_base64.txt

# On macOS, omit the -w flag:
sudo cat /etc/letsencrypt/live/smtp.yourdomain.com/fullchain.pem | base64 > cert_base64.txt
sudo cat /etc/letsencrypt/live/smtp.yourdomain.com/privkey.pem | base64 > key_base64.txt

​
Step 5: Add to Environment Variables

Copy the base64-encoded values to your .env file: 
SMTP_RELAY_ENABLED=true
SMTP_RELAY_DOMAIN=smtp.yourdomain.com
SMTP_RELAY_PORT=587
SMTP_RELAY_TLS_CERT_BASE64="<paste-cert-base64-here>"
SMTP_RELAY_TLS_KEY_BASE64="<paste-key-base64-here>"
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: 
# Using the provided script
./scripts/generate-dev-certs.sh localapi.notifuse.com

# Or manually with openssl
openssl req -x509 -newkey rsa:2048 \
  -keyout dev-cert.key.pem \
  -out dev-cert.cert.pem \
  -days 365 -nodes \
  -subj "/CN=localhost" \
  -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"

# Encode to base64
cat dev-cert.cert.pem | base64 > cert_base64.txt
cat dev-cert.key.pem | base64 > key_base64.txt
⚠️ 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.).