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
    • PASETO keys will be automatically generated
  4. Save the displayed PASETO keys securely
  5. Start using Notifuse!

​
One-click Deployments

Deploy Notifuse instantly with these one-click deployment options: Deploy on Railway 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 docker-compose.yml
curl -O https://raw.githubusercontent.com/notifuse/notifuse/main/docker-compose.yml

# 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 docker-compose.yml.

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

​
PASETO keys

PASETO keys are automatically generated during the Setup Wizard. The keys will be displayed at the end of setup - make sure to save them securely. If you prefer to generate keys manually or need to pre-configure via environment variables: 
# If you have the source code
make keygen

# Or directly with Go
go run cmd/keygen/main.go

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

​
A cron scheduler

The Notifuse API is 100% stateless: you can run many instances of it in parallel behind a load balancer. However, to trigger the automatic sending of emails, you will need to run a cron job that will call the https://YOUR_ENDPOINT/api/cron endpoint every minute. 
# Run every minute
* * * * * curl https://YOUR_ENDPOINT/api/cron > /dev/null 2>&1
When a newsletter campaign is being sent, the task is executed for at most 55 seconds and will wait for the next cron tick to continue its execution. You can set up a cron service in docker-compose.yml using the snippet below: 
cron:
  image: alpine:3.20
  restart: unless-stopped
  depends_on:
    - notifuse
  command: >
    /bin/sh -c "
      apk add --no-cache curl &&
      echo '* * * * * /usr/bin/curl https://YOUR_ENDPOINT/api/cron > /dev/null 2>&1' > /etc/crontabs/root &&
      crond -f -L /dev/stdout
    "

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

​
Database Variables (Required)

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 a random string)

​
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)
PASETO_PRIVATE_KEYBase64 encoded PASETO private key (auto-generated in wizard or generate at https://paseto.notifuse.com)
PASETO_PUBLIC_KEYBase64 encoded PASETO public key (auto-generated in wizard or generate at https://paseto.notifuse.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
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

​
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, PASETO keys) and the Setup Wizard or admin interface for non-sensitive settings (API endpoint, etc.).
⌘I