env.example

# Notifuse Environment Configuration
# Copy this file to .env and update the values below for your installation
#
# ⚠️  IMPORTANT: Special Characters in Values
# If your values contain the # character, you MUST wrap them in quotes:
#   CORRECT:   DB_PASSWORD="mypass#word123"
#   INCORRECT: DB_PASSWORD=mypass#word123   (will be truncated to "mypass")
#
# This limitation applies only to .env files. Environment variables set directly
# in your shell or container environment do not have this restriction.

# =============================================================================
# REQUIRED VARIABLES - Minimal configuration for first boot
# =============================================================================

# Secret key for encrypting sensitive data in the database (REQUIRED)
# Also used for:
#   - JWT token signing (HS256 symmetric)
#   - Magic code hashing (HMAC-SHA256)
#   - Root sign-in signatures
# Generate a secure random string and paste it below (a value giving less than
# 32 bytes is refused):
#   openssl rand -base64 32
# To replace it, list the new key first and the current one after a comma (from
# 42.0; an earlier version reads the list as a single key):
#   SECRET_KEY=<new key>,<current key>
# Stop every instance, then start them all with it: Notifuse re-encrypts the
# stored data with the new key when it starts. Once they all run, set the new
# key alone, without quotes or spaces around it. Everyone signs in again, API
# keys must be deleted and created again, pending invitations sent again, and
# scripts that call user.rootSignin or demo.reset sign with the new key. Backups
# taken before still need the former key. Write a comma that is part of a key
# twice.
SECRET_KEY=

# Database Configuration (Optional - compose.yaml has working defaults for Docker)
# Uncomment and modify only if using an external database or custom setup
# DB_HOST=postgres
# DB_PORT=5432
# DB_USER=postgres
# DB_PASSWORD=postgres
# DB_NAME=notifuse_system

# =============================================================================
# SETUP WIZARD - Configure via Web Interface (Recommended)
# =============================================================================
#
# On first boot, you'll be redirected to the setup wizard at /setup where you can:
# - Configure SMTP settings through a web form
# - Set up the admin account
# - Configure the API endpoint
#
# All settings below can be configured via the setup wizard and are stored
# securely in the database. You only need to set them here if you prefer
# environment-variable-based configuration or want to override database values.
#

# Root administrator email (Optional - can be set via setup wizard)
# ROOT_EMAIL=admin@yourcompany.com

# Public API endpoint URL (Optional - auto-detected via setup wizard)
# API_ENDPOINT=https://emails.yourcompany.com

# PASETO keys - DEPRECATED in v15.0
# For backward compatibility only: If SECRET_KEY is not set, PASETO_PRIVATE_KEY will be used
# PASETO_PRIVATE_KEY=your_base64_encoded_private_key_here

# SMTP Configuration (Optional - can be configured via setup wizard)
# SMTP_HOST=smtp.gmail.com
# SMTP_PORT=587
# SMTP_USERNAME=your-email@gmail.com
# SMTP_PASSWORD=your-app-password
# SMTP_FROM_EMAIL=noreply@yourcompany.com
# SMTP_FROM_NAME=Your Company Name

# SMTP Bridge Server Configuration (Optional - for receiving emails to trigger notifications)
# Legacy: SMTP_RELAY_* environment variables are still accepted for backward compatibility
# Enable this to receive emails that trigger transactional notifications via API
# Authentication uses SMTP AUTH with workspace_id as username and api_key as password
# 
# IMPORTANT: If SMTP_BRIDGE_ENABLED is explicitly set (even to "false"), the setup wizard
# will NOT be able to configure SMTP bridge - it will be locked to the env var value.
# Only leave this unset (commented out) if you want the setup wizard to configure it.
# SMTP_BRIDGE_ENABLED=false
# SMTP_BRIDGE_PORT=587
# SMTP_BRIDGE_DOMAIN=smtp.yourdomain.com

# TLS posture — one of: off | starttls | implicit
#   starttls  Default when certs are provided. Listens plaintext on port 587 and
#             requires clients to upgrade via STARTTLS before AUTH.
#   implicit  TLS-from-byte-1 (SMTPS). Set SMTP_BRIDGE_PORT=465. Works with
#             any dumb L4 TLS terminator if you want to front with a proxy.
#   off       No TLS at all. Only safe when fronted by a TLS-terminating
#             reverse proxy (Caddy layer4, HAProxy, nginx Mail, Postfix,
#             stunnel) on a trusted network. Required in production if you
#             don't want to manage certs inside Notifuse.
# SMTP_BRIDGE_TLS=starttls

# TLS Configuration (Base64 Encoded Certificates) — required for starttls and implicit modes
# Perfect for containers and secret managers - no file mounting needed
# To encode your certificates:
#   CERT_BASE64=$(cat /etc/letsencrypt/live/smtp.example.com/fullchain.pem | base64 -w 0)
#   KEY_BASE64=$(cat /etc/letsencrypt/live/smtp.example.com/privkey.pem | base64 -w 0)
# SMTP_BRIDGE_TLS_CERT_BASE64=LS0tLS1CRUdJTi...
# SMTP_BRIDGE_TLS_KEY_BASE64=LS0tLS1CRUdJTi...

# Getting Let's Encrypt Certificates:
# 1. Install certbot: apt-get install certbot (or brew install certbot)
# 2. Get certificate:
#    certbot certonly --standalone -d smtp.yourcompany.com
#    OR for DNS validation (no port 80 needed):
#    certbot certonly --manual --preferred-challenges dns -d smtp.yourcompany.com
# 3. Set auto-renewal:
#    certbot renew --deploy-hook "docker restart notifuse-api"

# =============================================================================
# LICENCE - Optional; unset is the free tier
# =============================================================================

# Notifuse licence key (Optional - leaving it unset is the ordinary state of a
# self-hosted installation and means the free tier)
#
# A licence lifts the free tier's limits: creating more than 3 workspaces,
# editing granular workspace permissions, provisioning SES tenants, and running
# the console with single sign-on enabled. Without a key, none of these are
# taken away retroactively - workspaces, permissions and SES tenants that
# already exist are untouched and keep working - but creating new ones is
# refused. Verification is entirely offline: the key is a signed token, and
# nothing about your installation is ever sent to Notifuse.
#
# One key covers one deployment (one Postgres database, whatever the number of
# API containers in front of it). Keys are delivered on purchase; the
# capabilities a key covers are listed at
# https://notifuse.com/licence-features
#
# A key can also be pasted in the console under Settings > Licence, which
# stores it in the database. THIS VARIABLE OVERRIDES THE STORED KEY, and while
# it is set the console's licence form refuses to save rather than writing a
# value that would lose to the environment on the next restart. Leave it unset
# if you want to manage the key from the console.
# NOTIFUSE_LICENSE_KEY=NFUSE1.eyJ2IjoxLC...

# =============================================================================
# OPTIONAL VARIABLES - Uncomment and modify if needed
# =============================================================================

# Privacy and Update Settings (Optional - can be configured via setup wizard)
# TELEMETRY=true                                # Send anonymous usage statistics (default: configured in setup wizard)
# CHECK_FOR_UPDATES=true                        # Check for new versions and security updates (default: configured in setup wizard)
# Note: If not set via environment variables, these will be configured via the setup wizard.
# Environment variables always take precedence over database settings.

# Server Configuration
# SERVER_PORT=8080
# SERVER_HOST=0.0.0.0
# CORS_ALLOW_ORIGIN=*
# ENVIRONMENT=production
# LOG_LEVEL=info

# Web Analytics: optional MaxMind GeoLite2/GeoIP2 City database for geo
# dimensions (country/region/city). Without a database, geo stays empty.
# A GeoLite2 City database ships with Notifuse at /app/geoip/GeoLite2-City.mmdb
# and is used automatically. To use a fresher or commercial copy, drop it in the
# mounted data directory as GeoLite2-City.mmdb (it takes precedence) or set this
# variable (see https://github.com/maxmind/geoipupdate).
# GEOIP_DB_PATH=/app/data/GeoLite2-City.mmdb

# Database Configuration (for custom setups)
# DB_PREFIX=notifuse
# DB_NAME=notifuse_system
# DB_SSLMODE=require

# Database Connection Pool Settings
# DB_MAX_CONNECTIONS=100                    # Total max connections across all databases (default: 100)
# DB_MAX_CONNECTIONS_PER_DB=3               # Max connections per workspace database (default: 3)
# DB_CONNECTION_MAX_LIFETIME=10m            # Maximum lifetime of a connection (default: 10m)
# DB_CONNECTION_MAX_IDLE_TIME=5m            # Maximum idle time before closing (default: 5m)

# Task Scheduler Configuration
# The internal scheduler handles task execution automatically
# TASK_SCHEDULER_ENABLED=true               # Enable/disable internal scheduler (default: true)
# TASK_SCHEDULER_INTERVAL=30s               # How often to check for pending tasks (default: 30s)
# TASK_SCHEDULER_MAX_TASKS=100              # Max tasks to process per execution (default: 100)

# Broadcast Data Feeds
# Broadcasts can fetch external JSON data feeds (global and per-recipient) to
# personalize content. By default these outbound requests are SSRF-protected:
# the server refuses to connect to private, loopback, link-local, and reserved
# IP ranges (including the cloud instance metadata endpoint).
# Enable the option below ONLY in trusted, self-hosted deployments that
# intentionally point data feeds at services on their internal/private network.
# Turning it on disables SSRF protection for data-feed requests.
# BROADCAST_DATA_FEED_ALLOW_PRIVATE_HOSTS=false

# Outgoing Webhooks
# Webhook subscriptions and automation webhook nodes post events to a URL
# supplied by a workspace member. By default these outbound requests are
# SSRF-protected: the server refuses to connect to private, loopback,
# link-local, and reserved IP ranges (including the cloud instance metadata
# endpoint), on the first hop and on every redirect, and refuses to save a
# subscription or an automation webhook node that names such a target.
# Enable the option below ONLY in trusted, self-hosted deployments that
# intentionally deliver webhooks to services on their internal/private network
# (e.g. n8n on the same Docker network). With it off, outgoing webhooks also
# connect directly and ignore HTTP_PROXY/HTTPS_PROXY.
# Turning it on disables SSRF protection for outgoing webhooks.
# WEBHOOK_DELIVERY_ALLOW_PRIVATE_HOSTS=false

# Plan limits (set by Notifuse Cloud; leave unset when self-hosting)
# Every limit below is 0 = unlimited, which is what an unset variable resolves
# to - a self-hosted installation is never limited by these. A negative value is
# rejected at startup.
# PLAN_MAX_ACTIVE_CONTACTS=0                # Max contacts active in the billing period
# PLAN_MAX_STORED_CONTACTS=0                # Max contacts stored in total
# PLAN_MAX_MONTHLY_EVENTS=0                 # Max events recorded per month
# PLAN_MAX_MONTHLY_PAGEVIEWS=0              # Max web analytics pageviews per month
# PLAN_DATA_RETENTION_MONTHS=0              # Months of history kept
# MAX_USERS=0                               # Max team members across the installation
# MAX_WORKSPACES=0                          # Max workspaces that can be created

# Tracing Configuration
# TRACING_ENABLED=false
# TRACING_SERVICE_NAME=notifuse-api
# TRACING_SAMPLING_PROBABILITY=0.1
# TRACING_TRACE_EXPORTER=none
# TRACING_JAEGER_ENDPOINT=http://localhost:14268/api/traces
# TRACING_ZIPKIN_ENDPOINT=http://localhost:9411/api/v2/spans
# TRACING_STACKDRIVER_PROJECT_ID=
# TRACING_AZURE_INSTRUMENTATION_KEY=
# TRACING_DATADOG_AGENT_ADDRESS=localhost:8126
# TRACING_DATADOG_API_KEY=
# TRACING_XRAY_REGION=us-west-2
# TRACING_AGENT_ENDPOINT=localhost:8126
# TRACING_METRICS_EXPORTER=none
# TRACING_PROMETHEUS_PORT=9464