Saltar al contenido

Autoalojamiento

Instalación autoalojada

Cómo autoalojar Notifuse

Consejo

¿Buscas una solución gestionada? Notifuse Cloud se encarga del alojamiento, la seguridad, las copias de seguridad, las actualizaciones y el mantenimiento, desde 16 $/mes.

Primeros pasos

Notifuse incluye un asistente de configuración interactivo. Muchas variables de entorno son opcionales y se pueden definir en la interfaz web en el primer arranque.

El asistente de configuración completado: administrador, envío de correos del sistema (SMTP), actualizaciones y telemetría, inicio de sesión único y puente SMTP, con lo que queda por completar al lado

Inicio rápido con el asistente de configuración

  1. Despliega Notifuse con una de las opciones de abajo
  2. Abre tu instancia en un navegador web
  3. Completa el asistente de configuración:
    • Introduce el correo del administrador root (uno o varios)
    • Comprueba el endpoint de la API, rellenado con la dirección de la página
    • Configura el servidor SMTP que envía los códigos de inicio de sesión y las invitaciones, y prueba la conexión
    • Mantén o desactiva la búsqueda de actualizaciones y la telemetría anónima (las dos activadas por defecto)
    • Si quieres, configura el inicio de sesión único (OpenID Connect) y el puente SMTP
  4. Empieza a usar Notifuse.

Un ajuste que ya viene de una variable de entorno aparece bloqueado en el asistente, con el nombre de la variable, y el asistente no lo pide.

compose.yaml ejecuta Notifuse con su propio PostgreSQL 18. El archivo funciona por sí solo: el servidor no necesita un clon del repositorio, solo Docker Engine 25.0 y Compose v2.24 o posterior (docker compose version).

Advertencia

Estos pasos crean una instalación nueva. Para actualizar una que ya funciona, conserva su .env y la SECRET_KEY que contiene, porque una clave nueva por sí sola deja ilegibles tus datos guardados (consulta Actualizar). Una instalación iniciada desde compose.yaml antes de la versión 42.0 sin definir SECRET_KEY usa un valor por defecto que Notifuse ahora rechaza: Sustituir la clave secreta indica ese valor por defecto y el cambio que hay que hacer.

mkdir notifuse && cd notifuse
curl -fsSL https://raw.githubusercontent.com/Notifuse/notifuse/main/compose.yaml -o compose.yaml

# Generate the secret key and the database password once, and keep them:
# the key encrypts your stored data. An existing .env is left alone.
test -e .env || cat > .env <<EOF
SECRET_KEY=$(openssl rand -base64 32)
DB_PASSWORD=$(openssl rand -hex 24)
EOF

docker compose up -d

Esto inicia Notifuse en el puerto 8081, con PostgreSQL accesible solo desde el propio servidor (127.0.0.1:5433). En el primer arranque, el asistente de configuración te guía para configurar Notifuse. También puedes definir variables de entorno en el archivo .env: todas las variables que contiene llegan a Notifuse.

Notifuse sirve HTTP sin cifrar. Pon delante un proxy inverso con TLS antes de apuntar un dominio a él, y define HTTP_BIND=127.0.0.1 en .env cuando ese proxy se ejecute en el mismo servidor.

Advertencia

Compose da al volumen de la base de datos el nombre del directorio que contiene compose.yaml (aquí notifuse_postgres-data). No cambies el nombre de ese directorio: en un directorio renombrado o movido, docker compose up -d inicia una instalación nueva sobre una base de datos vacía. docker compose down -v borra la base de datos.

Actualizar una instalación Docker Compose

Lee las entradas del registro de cambios entre tu versión y la nueva, haz una copia de seguridad, descarga el compose.yaml de la nueva versión sobre el tuyo (o define NOTIFUSE_VERSION=v44.0 en .env para elegir la versión) y ejecuta docker compose up -d.

La versión 44.0 pasa compose.yaml a PostgreSQL 18: el primer docker compose up -d copia tus datos de PostgreSQL 17 a un segundo volumen y luego los actualiza. Actualizar PostgreSQL explica qué ocurre, cómo comprobarlo y cómo volver atrás.

Desde un clon del repositorio

El mismo archivo compila Notifuse desde el código fuente en un clon: docker compose up -d --build, o docker compose watch para recompilar con cada cambio. Sin --build, ejecuta la imagen publicada para la versión que indica el archivo. Una versión que aún no se ha publicado, en la rama dev, se compila desde la copia local. Hasta la versión 43, compose.yaml siempre compilaba desde la copia local.

Opción 2: Docker independiente (producción)

Para despliegues en producción, usa la imagen Docker independiente con tu propia base de datos PostgreSQL:

# Generate SECRET_KEY once with: openssl rand -base64 32, and keep it: it encrypts your stored data
docker run -d --name notifuse -p 8080:8080 \
  -e SECRET_KEY=<your secret key> \
  notifuse/notifuse:latest

En el primer arranque, el asistente de configuración te guía para configurar Notifuse. También puedes definir variables de entorno.

Base de datos PostgreSQL (solo opción 2)

Con la opción Docker independiente, puedes usar cualquier base de datos PostgreSQL con credenciales root. Notifuse crea su propia base de datos del sistema.

Versión: PostgreSQL 17 o posterior (Notifuse se niega a arrancar en un servidor más antiguo). compose.yaml incluye PostgreSQL 18

Notifuse crea una base de datos por espacio de trabajo para evitar los problemas del multi-tenant, y por eso necesita credenciales root.

Nota: Docker Compose incluye PostgreSQL, así que esto no se aplica en ese caso.

Un servidor SMTP

Notifuse necesita un servidor SMTP para enviar los correos del sistema, como los códigos de inicio de sesión y los correos de invitación.

Con SES, puedes crear credenciales SMTP en la sección de ajustes SMTP del panel de SES.

Un endpoint de API público

Notifuse necesita un endpoint de API público accesible desde la web, por ejemplo https://emails.yourcompany.com.

Detrás de un proxy inverso, reenvía a Notifuse la cabecera Host original, o pon su valor en X-Forwarded-Host. Las versiones web de los correos solo se abren en el dominio con el que se envió su enlace y en API_ENDPOINT. Un proxy que sustituye Host por su dirección upstream, sin definir X-Forwarded-Host, deja todas las versiones web inaccesibles. Uno que la sustituye por el host de API_ENDPOINT permite que cualquier dominio personalizado muestre las versiones web de todos los espacios de trabajo.

Variables de entorno

Con el asistente de configuración, muchas variables de entorno son opcionales y se pueden definir en la interfaz web. Una variable de entorno definida siempre tiene prioridad sobre el ajuste guardado en la base de datos.

Advertencia

Caracteres especiales en los archivos .env

En un archivo .env, un valor que contiene el carácter # (habitual en las contraseñas) debe ir entre comillas:

# ✅ CORRECT - value is quoted
DB_PASSWORD="mypass#word123"
SMTP_PASSWORD="smtp#pass456"

# ❌ INCORRECT - will be truncated at the # character
DB_PASSWORD=mypass#word123   # parsed as "mypass"
SMTP_PASSWORD=smtp#pass456   # parsed as "smtp"

Esto solo se aplica a los archivos .env, no a las variables definidas directamente en tu shell, en Docker Compose o en una plataforma de orquestación de contenedores.

Variables obligatorias

VariableDescripción
DB_HOSTHost de PostgreSQL (p. ej., localhost o db.yourcompany.com)
DB_PORTPuerto de PostgreSQL (p. ej., 5432)
DB_USERUsuario de la base de datos (p. ej., postgres)
DB_PASSWORDContraseña de la base de datos (p. ej., postgres)
SECRET_KEYClave secreta para el cifrado y la firma (se genera con el comando de abajo)

Generar SECRET_KEY:

openssl rand -base64 32

Notifuse se niega a arrancar con una SECRET_KEY de menos de 32 bytes.

Advertencia

No sustituyas nunca tu SECRET_KEY por un valor nuevo sin más. Cifra todos los secretos de las integraciones de los espacios de trabajo (claves API de proveedores de correo, contraseñas SMTP, etc.), que una clave nueva por sí sola no puede leer. Para cambiarla, sigue Sustituir la clave secreta.

Sustituir la clave secreta

SECRET_KEY puede contener varias claves separadas por comas (una coma que forma parte de una clave se escribe dos veces). La primera clave cifra y firma. Las demás solo permiten a Notifuse leer los datos guardados con ellas. Cuando Notifuse arranca con una lista, vuelve a cifrar esos datos con la primera clave, en una sola transacción, antes de servir nada. Para sustituir tu clave:

  1. Genera una clave nueva con openssl rand -base64 32.
  2. Ponla en primer lugar y tu clave actual después: SECRET_KEY=<new key>,<current key>. Si tu clave actual contiene una coma, escribe esa coma dos veces, y si empieza o termina con una, pon un espacio entre ella y la coma que separa las claves (SECRET_KEY=<new key>, ,,<rest of the key>). Una versión anterior a 42.0 lee toda la lista como una sola clave: cuando actualices a 42.0, define la lista en el mismo paso.
  3. Detén todas las instancias de Notifuse y luego inícialas todas con ese valor. Una instancia que sigue funcionando solo con la clave actual no puede leer los datos que las otras volvieron a cifrar, y una instancia con la lista no puede leer lo que escribe esa instancia hasta el siguiente arranque con la lista.
  4. Cuando todas las instancias funcionen con ese valor, define SECRET_KEY con la clave nueva sola, sin comillas ni espacios alrededor: una clave única se usa tal como está escrita. Si no abre ninguno de los espacios de trabajo guardados (o, mientras no haya ninguno, ninguno de los ajustes cifrados del sistema), Notifuse no arranca.

Si la clave de un espacio de trabajo, o una credencial que usa, no se abre con ninguna de las claves de la lista, Notifuse no arranca, no cambia nada e indica qué espacio de trabajo es. Un ajuste cifrado del sistema que ninguna de ellas abre (una credencial SMTP o el client secret OIDC guardados en el asistente de configuración, el certificado TLS del puente SMTP o su clave) se deja tal cual y se indica en una advertencia de los registros de arranque, y Notifuse funciona sin él. Para conservarlo, añade a la lista la clave con la que está cifrado. Notifuse no arranca, e indica el ajuste, cuando el inicio de sesión único o el puente SMTP están activados y lo necesitan, o cuando aún no hay ningún espacio de trabajo guardado y ninguno de esos ajustes se abre.

Sustituir la clave cierra la sesión de todo el mundo. Hay que borrar y volver a crear las claves API, volver a enviar las invitaciones pendientes, y los scripts que llaman a user.rootSignin firman con la clave nueva. Un cliente de API que guarda una integración con las credenciales cifradas que leyó antes del cambio recibe un rechazo hasta que vuelve a leer el espacio de trabajo. Las copias de seguridad de la base de datos hechas antes del cambio siguen necesitando la clave anterior. Los datos guardados en la base de datos de cada espacio de trabajo, como el historial de mensajes, están cifrados con la clave propia de ese espacio de trabajo y no se ven afectados.

Advertencia

Antes de la versión 42.0, compose.yaml traía una SECRET_KEY por defecto y env.example un valor de ejemplo. Notifuse se niega a arrancar cuando la primera clave de SECRET_KEY es uno de esos valores o tiene menos de 32 bytes, y lee una sola coma como separador entre claves: si tu clave contiene una coma, escribe cada una de sus comas dos veces al actualizar. Si tu instalación funciona con uno de esos valores, sustitúyelo como se explica arriba, manteniéndolo después de la clave nueva, en el mismo paso que la actualización a 42.0. Si empezaste desde compose.yaml sin definir SECRET_KEY, tu clave actual es el antiguo valor por defecto:

# Put the output of openssl rand -base64 32 before the comma
SECRET_KEY=<new key>,d04zCk3Fa45oOjDWHpAvc1AZxnLdGffOnNWK+Jt2yXf37+FTfuMMHb8flcfPMqLluRR3rvhbr555r6j1DEigrA==

Variables de la aplicación (opcionales con el asistente de configuración)

Defínelas en el asistente de configuración en el primer arranque, o como variables de entorno, que siempre tienen prioridad sobre el asistente.

VariableDescripción
ROOT_EMAILCorreo del administrador root (p. ej., admin@yourcompany.com). Acepta varios correos separados por comas o punto y coma para dar acceso root a varios administradores (p. ej., alice@yourcompany.com,bob@yourcompany.com). La comparación distingue mayúsculas y minúsculas.
API_ENDPOINTURL pública del endpoint de la API (p. ej., https://emails.yourcompany.com). Para pasar más adelante a otro dominio, consulta Cambiar de dominio.
SMTP_HOSTHost del servidor SMTP (p. ej., smtp.gmail.com)
SMTP_PORTPuerto del servidor SMTP (p. ej., 587 o 465)
SMTP_USERNAMEUsuario SMTP (p. ej., noreply@yourcompany.com)
SMTP_PASSWORDContraseña SMTP (p. ej., your_smtp_password)
SMTP_FROM_EMAILDirección del remitente (p. ej., noreply@yourcompany.com)
SMTP_FROM_NAMENombre del remitente (p. ej., Your Company Name)
SMTP_EHLO_HOSTNAMENombre de host EHLO personalizado para las conexiones SMTP (p. ej., mail.yourdomain.com). Si está vacío, se usa el host SMTP. Útil cuando los servidores SMTP rechazan EHLO localhost.

Nota

Varios usuarios root: ROOT_EMAIL puede contener más de un correo (separados por comas o punto y coma), así que una instancia compartida puede tener varios administradores con privilegios root: crear espacios de trabajo, acceder a la configuración del sistema y autenticarse de forma programática. Notifuse crea una cuenta de usuario para cada correo de la lista al arrancar, así que cada root puede iniciar sesión de inmediato. La comparación distingue mayúsculas y minúsculas, y un solo correo funciona exactamente igual que antes. El asistente de configuración define el primer root (el principal). Añade más allí como lista o con la variable de entorno ROOT_EMAIL.

Variables opcionales

VariableDescripciónValor por defecto
Configuración del servidor
SERVER_PORTPuerto en el que escucha el servidor (p. ej., 8080)8080
SERVER_HOSTDirección del host a la que se vincula (p. ej., 0.0.0.0)0.0.0.0
CORS_ALLOW_ORIGINOrígenes que pueden llamar a la API desde un navegador: *, un origen o una lista separada por comas (p. ej., https://yourapp.com,https://admin.yourapp.com; las listas necesitan 41.1 o posterior). Un valor restringido debe incluir todos los dominios personalizados de los espacios de trabajo, cuya consola y centro de notificaciones llaman a la API desde su propio origen.*
ENVIRONMENTModo de entorno (p. ej., production)production
LOG_LEVELNivel de registro (p. ej., debug o warn)info
Configuración de la base de datos
DB_PREFIXPrefijo de nombre para la base de datos del sistema y las de cada espacio de trabajo (p. ej., notifuse para notifuse_system y notifuse_ws_*)notifuse
DB_NAMENombre de la base de datos (p. ej., notifuse_system)${DB_PREFIX}_system
DB_SSLMODEModo SSL de la base de datos (p. ej., require o disable)require
DB_EXPECT_EXISTINGCon true, Notifuse se niega a crear o inicializar la base de datos del sistema y a crear una base de datos de espacio de trabajo que falte. Defínela en un servidor que ya debe contener los datos (una actualización, una restauración), para que un PostgreSQL vacío detenga Notifuse en lugar de iniciar una instalación nuevafalse
DB_MAX_CONNECTIONSMáximo total de conexiones entre todas las bases de datos (p. ej., 100)100
DB_MAX_CONNECTIONS_PER_DBMáximo de conexiones por base de datos de espacio de trabajo (p. ej., 3)3
DB_CONNECTION_MAX_LIFETIMEDuración máxima de una conexión (p. ej., 10m)10m
DB_CONNECTION_MAX_IDLE_TIMETiempo máximo de inactividad antes de cerrar la conexión (p. ej., 5m)5m
Configuración del programador de tareas
TASK_SCHEDULER_ENABLEDActiva el programador de tareas interno (p. ej., true o false)true
TASK_SCHEDULER_INTERVALIntervalo de ejecución de las tareas en segundos (p. ej., 30)30
TASK_SCHEDULER_MAX_TASKSMáximo de tareas simultáneas (p. ej., 10)10
Configuración de los envíos masivos
BROADCAST_DATA_FEED_ALLOW_PRIVATE_HOSTSPermite que las fuentes de datos de los envíos masivos consulten direcciones privadas, de loopback y de enlace local. Esto desactiva la protección SSRF para las peticiones de las fuentes de datos: actívalo solo en despliegues de confianza que consultan fuentes de datos de tu red interna a propósito (p. ej., true).false
EMAIL_QUEUE_CONCURRENCYCorreos que envía a la vez cada integración de correo distinta de SMTP para envíos masivos y automatizaciones, por instancia de Notifuse, entre 1 y 50 (p. ej., 20; 42.0 o posterior). Consulta Velocidad de envío.10
EMAIL_QUEUE_SMTP_CONCURRENCYLo mismo para las integraciones SMTP, entre 1 y 50 (42.0 o posterior). Súbelo solo si tu servidor SMTP acepta varias conexiones a la vez (p. ej., 4).1
Configuración de los webhooks
WEBHOOK_DELIVERY_ALLOW_PRIVATE_HOSTSPermite que los webhooks salientes (suscripciones de webhook y nodos webhook de las automatizaciones) lleguen a direcciones privadas, de loopback y de enlace local. Esto desactiva la protección SSRF para ellos: actívalo solo en despliegues de confianza que entregan webhooks a tu red interna a propósito, como n8n en la misma red Docker (p. ej., true). Mientras está desactivado, los webhooks salientes se conectan directamente e ignoran HTTP_PROXY/HTTPS_PROXY.false
Licencia
NOTIFUSE_LICENSE_KEYUna clave de licencia autoalojada. Tiene prioridad sobre una clave pegada en la consola. No hace falta para usar Notifuse.-
Privacidad
TELEMETRYEnvía estadísticas de uso anónimas (p. ej., true o false)true
CHECK_FOR_UPDATESBusca nuevas versiones (p. ej., true o false)true
Configuración del puente SMTP
SMTP_BRIDGE_ENABLEDActiva el servidor del puente SMTP para los correos transaccionales (p. ej., true o false)false
SMTP_BRIDGE_PORTPuerto del puente SMTP (p. ej., 587 para STARTTLS, 465 para TLS implícito)587
SMTP_BRIDGE_DOMAINNombre de dominio público del puente SMTP (p. ej., smtp.yourdomain.com)localhost
SMTP_BRIDGE_TLSModo TLS: starttls, implicit u off (ver más abajo). Se resuelve automáticamente si no se define.auto
SMTP_BRIDGE_TLS_CERT_BASE64Certificado TLS codificado en base64 (obligatorio para starttls e implicit)-
SMTP_BRIDGE_TLS_KEY_BASE64Clave privada TLS codificada en base64 (obligatoria para starttls e implicit)-
Inicio de sesión único (OIDC) (consulta la guía de SSO)
OIDC_ENABLEDActiva el inicio de sesión único mediante OpenID Connect (p. ej., true o false)false
OIDC_ISSUER_URLURL del emisor del IdP, debe ser https (p. ej., https://accounts.google.com)-
OIDC_CLIENT_IDClient ID OAuth2 de tu proveedor de identidad-
OIDC_CLIENT_SECRETClient secret OAuth2 (se guarda cifrado y nunca se envía al navegador)-
OIDC_REDIRECT_URIURL de callback registrada en el IdP. Se deriva de API_ENDPOINT si está vacía.<API_ENDPOINT>/api/user.oidc.callback
OIDC_SCOPESScopes separados por espacios (openid siempre se incluye)openid email profile
OIDC_BUTTON_LABELTexto del botón de inicio de sesiónSign in with SSO
OIDC_AUTO_CREATE_USERSCrea cuentas automáticamente en el primer inicio de sesión SSO (requiere OIDC_ALLOWED_DOMAINS)false
OIDC_ALLOWED_DOMAINSLista de dominios de correo permitidos, separados por comas o punto y coma, que limita la creación automática-
Configuración del tracing
TRACING_ENABLEDActiva el tracing (p. ej., true)false
TRACING_SERVICE_NAMENombre del servicio para el tracing (p. ej., notifuse-production)notifuse-api
TRACING_SAMPLING_PROBABILITYProbabilidad de muestreo (p. ej., 0.05)0.1
TRACING_TRACE_EXPORTERExportador de trazas: jaeger/zipkin/stackdriver/datadog/xray/none (p. ej., jaeger o datadog)none
TRACING_JAEGER_ENDPOINTEndpoint de Jaeger (p. ej., http://jaeger:14268/api/traces)http://localhost:14268/api/traces
TRACING_ZIPKIN_ENDPOINTEndpoint de Zipkin (p. ej., http://zipkin:9411/api/v2/spans)http://localhost:9411/api/v2/spans
TRACING_STACKDRIVER_PROJECT_IDID del proyecto de Stackdriver (p. ej., my-gcp-project-id)-
TRACING_AZURE_INSTRUMENTATION_KEYClave de instrumentación de Azure Monitor (p. ej., 12345678-1234-1234-1234-123456789012)-
TRACING_DATADOG_AGENT_ADDRESSDirección del agente de Datadog (p. ej., datadog-agent:8126)localhost:8126
TRACING_DATADOG_API_KEYClave API de Datadog (p. ej., 1234567890abcdef1234567890abcdef)-
TRACING_XRAY_REGIONRegión de AWS X-Ray (p. ej., us-east-1)us-west-2
TRACING_AGENT_ENDPOINTEndpoint general del agente (p. ej., monitoring-agent:8126)localhost:8126
TRACING_METRICS_EXPORTERExportador de métricas: stackdriver/prometheus/datadog/none (p. ej., prometheus)none
TRACING_PROMETHEUS_PORTPuerto de las métricas de Prometheus (p. ej., 9464)9464

Configuración del puente SMTP

El puente SMTP conecta con Notifuse las aplicaciones SaaS que solo ofrecen una integración SMTP (como Supabase Auth, Firebase o Auth0), para que sus correos usen los diseños y la imagen de marca que creas en el editor MJML de Notifuse en lugar de las plantillas por defecto del SaaS.

Consulta la documentación de uso del puente SMTP para ver ejemplos de envío una vez configurado.

Modos TLS

El puente admite tres modos TLS mediante SMTP_BRIDGE_TLS:

ModoDescripciónPuerto habitual
starttlsEscucha en texto plano. Los clientes deben pasar a TLS con STARTTLS antes de AUTH. Es el modo por defecto cuando se proporcionan certificados.587
implicitTLS desde el primer byte (SMTPS). Necesario para los clientes que solo hablan TLS implícito.465
offSin TLS. Solo es seguro detrás de un proxy inverso que termina TLS (HAProxy, Caddy layer4, stunnel, nginx Mail, Postfix) en una red de confianza.cualquiera

Cuando SMTP_BRIDGE_TLS no está definida, Notifuse elige starttls si se proporcionan el certificado y la clave, y si no, off en desarrollo.

Advertencia

En producción (ENVIRONMENT=production), el puente se niega a arrancar sin TLS configurado. Proporciona SMTP_BRIDGE_TLS_CERT_BASE64 y SMTP_BRIDGE_TLS_KEY_BASE64, o define SMTP_BRIDGE_TLS=off explícitamente si usas un proxy inverso que termina TLS.

Configuración de producción con Let’s Encrypt

En producción, usa certificados TLS válidos de Let’s Encrypt, obtenidos con certbot y un desafío DNS.

Paso 1: instalar Certbot

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

# macOS
brew install certbot

# CentOS/RHEL
sudo yum install certbot

Paso 2: generar el certificado con un desafío DNS

Se recomienda un desafío DNS: no necesita los puertos 80 ni 443 abiertos y funciona aunque tu servidor SMTP esté en otro puerto.

# Generate certificate using DNS challenge
sudo certbot certonly \
  --manual \
  --preferred-challenges dns \
  --email admin@yourdomain.com \
  --agree-tos \
  -d smtp.yourdomain.com

Certbot te pide entonces que crees un registro DNS TXT:

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

Paso 3: añadir el registro DNS TXT

Añade el registro TXT en tu proveedor DNS:

Type: TXT
Name: _acme-challenge.smtp
Value: XyZ123AbC456... (the value provided by certbot)
TTL: 300 (5 minutes)

Espera unos minutos a que se propague el DNS y luego comprueba el registro:

dig -t txt _acme-challenge.smtp.yourdomain.com

# Or using nslookup
nslookup -type=TXT _acme-challenge.smtp.yourdomain.com

Pulsa Intro en certbot para continuar cuando el registro esté verificado.

Paso 4: codificar los certificados en base64

Cuando certbot haya generado los certificados, codifícalos en 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

Paso 5: añadirlos a las variables de entorno

Copia los valores codificados en base64 en tu archivo .env:

SMTP_BRIDGE_ENABLED=true
SMTP_BRIDGE_DOMAIN=smtp.yourdomain.com
SMTP_BRIDGE_PORT=587
SMTP_BRIDGE_TLS=starttls
SMTP_BRIDGE_TLS_CERT_BASE64="<paste-cert-base64-here>"
SMTP_BRIDGE_TLS_KEY_BASE64="<paste-key-base64-here>"

Nota

Certbot configura una tarea cron de renovación. Después de cada renovación, vuelve a codificar los certificados en base64 y actualiza tus variables de entorno.

Configuración de desarrollo con certificados autofirmados

Para el desarrollo local, puedes usar certificados autofirmados:

# 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

Advertencia: los certificados autofirmados son solo para desarrollo. No los uses nunca en producción.

Gestión de la configuración

El asistente de configuración sirve para despliegues rápidos y pruebas: guarda la configuración de forma segura en la base de datos, y la gestionas desde la interfaz web. En producción se recomiendan las variables de entorno: protegen mejor los datos sensibles y permiten que tu pipeline de despliegue gestione la configuración. Cuando existen las dos, la variable de entorno siempre tiene prioridad.

En producción, recomendamos variables de entorno para la configuración sensible (credenciales SMTP, SECRET_KEY) y el asistente de configuración o la interfaz de administración para el resto (endpoint de la API, etc.).

Autenticación programática

En pipelines de CI/CD y despliegues automatizados, un usuario root puede autenticarse de forma programática con una firma HMAC-SHA256 en lugar de un enlace mágico. Cuando ROOT_EMAIL contiene varias direcciones, usa cualquiera de ellas como ROOT_EMAIL en el ejemplo siguiente: el correo firmado debe coincidir exactamente con uno de los correos root configurados.

#!/bin/bash
# Configuration
NOTIFUSE_URL="https://your-notifuse-instance.com"
SECRET_KEY="your-secret-key"  # the first key when SECRET_KEY lists several
ROOT_EMAIL="admin@example.com"
TIMESTAMP=$(date +%s)

# Generate HMAC signature
MESSAGE="${ROOT_EMAIL}:${TIMESTAMP}"
SIGNATURE=$(echo -n "$MESSAGE" | openssl dgst -sha256 -hmac "$SECRET_KEY" | awk '{print $2}')

# Authenticate and get JWT token
curl -X POST "${NOTIFUSE_URL}/api/user.rootSignin" \
  -H "Content-Type: application/json" \
  -d "{\"email\":\"${ROOT_EMAIL}\",\"timestamp\":${TIMESTAMP},\"signature\":\"${SIGNATURE}\"}"

El endpoint devuelve un token JWT para las siguientes peticiones a la API. Las marcas de tiempo deben estar a menos de 60 segundos de la hora del servidor, y las peticiones están limitadas a 5 intentos cada 5 minutos.

Plataformas de alojamiento de terceros

Notifuse también está disponible en las siguientes plataformas de terceros.

Advertencia

Estas plataformas no tienen soporte oficial y a menudo ejecutan versiones antiguas de Notifuse. Para tener la última versión, actualizaciones automáticas y soporte oficial, usa Notifuse Cloud.