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.
Known Issue with SMTP Configuration: A bug has been discovered with SMTP variables configured through the Setup Wizard. To ensure reliable email delivery, we recommend setting SMTP environment variables (SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, SMTP_FROM_EMAIL, SMTP_FROM_NAME) directly in your environment or .env file instead of using the Setup Wizard for SMTP configuration.
Quick Start with Setup Wizard
- Deploy Notifuse using one of the options below
- Access your instance in a web browser
- Complete the Setup Wizard:
- Enter your root administrator email
- Configure your API endpoint
- Set up SMTP settings
- PASETO keys will be automatically generated
- Save the displayed PASETO keys securely
- Start using Notifuse!
One-click Deployments
Deploy Notifuse instantly with these one-click deployment options:
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:
Option 1: Docker Compose (Recommended for testing)
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
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
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
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)
| Variable | Description |
|---|
DB_HOST | PostgreSQL host (e.g., localhost or db.yourcompany.com) |
DB_PORT | PostgreSQL port (e.g., 5432) |
DB_USER | Database username (e.g., postgres) |
DB_PASSWORD | Database password (e.g., postgres) |
SECRET_KEY | Secret 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.
| Variable | Description |
|---|
ROOT_EMAIL | Root administrator email (e.g., admin@yourcompany.com) |
API_ENDPOINT | Public API endpoint URL (e.g., https://emails.yourcompany.com) |
PASETO_PRIVATE_KEY | Base64 encoded PASETO private key (auto-generated in wizard or generate at https://paseto.notifuse.com) |
PASETO_PUBLIC_KEY | Base64 encoded PASETO public key (auto-generated in wizard or generate at https://paseto.notifuse.com) |
SMTP_HOST | SMTP server host (e.g., smtp.gmail.com) |
SMTP_PORT | SMTP server port (e.g., 587 or 465) |
SMTP_USERNAME | SMTP username (e.g., noreply@yourcompany.com) |
SMTP_PASSWORD | SMTP password (e.g., your_smtp_password) |
SMTP_FROM_EMAIL | From email address (e.g., noreply@yourcompany.com) |
SMTP_FROM_NAME | From name (e.g., Your Company Name) |
Optional Variables
| Variable | Description | Default |
|---|
| Server Configuration | | |
SERVER_PORT | Port for the server to listen on (e.g., 8080) | 8080 |
SERVER_HOST | Host address to bind to (e.g., 0.0.0.0) | 0.0.0.0 |
CORS_ALLOW_ORIGIN | CORS allowed origins (e.g., https://yourapp.com,https://admin.yourapp.com) | * |
ENVIRONMENT | Environment mode (e.g., production) | production |
LOG_LEVEL | Logging level (e.g., debug or warn) | info |
| Database Configuration | | |
DB_PREFIX | Database table prefix (e.g., notifuse) | notifuse |
DB_NAME | Database name (e.g., notifuse_system) | ${DB_PREFIX}_system |
DB_SSLMODE | SSL mode for database (e.g., require or disable) | require |
| Tracing Configuration | | |
TRACING_ENABLED | Enable tracing (e.g., true) | false |
TRACING_SERVICE_NAME | Service name for tracing (e.g., notifuse-production) | notifuse-api |
TRACING_SAMPLING_PROBABILITY | Sampling probability (e.g., 0.05) | 0.1 |
TRACING_TRACE_EXPORTER | Trace exporter: jaeger/zipkin/stackdriver/datadog/xray/none (e.g., jaeger or datadog) | none |
TRACING_JAEGER_ENDPOINT | Jaeger endpoint (e.g., http://jaeger:14268/api/traces) | http://localhost:14268/api/traces |
TRACING_ZIPKIN_ENDPOINT | Zipkin endpoint (e.g., http://zipkin:9411/api/v2/spans) | http://localhost:9411/api/v2/spans |
TRACING_STACKDRIVER_PROJECT_ID | Stackdriver project ID (e.g., my-gcp-project-id) | - |
TRACING_AZURE_INSTRUMENTATION_KEY | Azure Monitor instrumentation key (e.g., 12345678-1234-1234-1234-123456789012) | - |
TRACING_DATADOG_AGENT_ADDRESS | Datadog agent address (e.g., datadog-agent:8126) | localhost:8126 |
TRACING_DATADOG_API_KEY | Datadog API key (e.g., 1234567890abcdef1234567890abcdef) | - |
TRACING_XRAY_REGION | AWS X-Ray region (e.g., us-east-1) | us-west-2 |
TRACING_AGENT_ENDPOINT | General agent endpoint (e.g., monitoring-agent:8126) | localhost:8126 |
TRACING_METRICS_EXPORTER | Metrics exporter: stackdriver/prometheus/datadog/none (e.g., prometheus) | none |
TRACING_PROMETHEUS_PORT | Prometheus 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.).