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.
Inicio rápido con el asistente de configuración
- Despliega Notifuse con una de las opciones de abajo
- Abre tu instancia en un navegador web
- 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
- 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.
Opción 1: Docker Compose (recomendada)
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
| Variable | Descripción |
|---|---|
DB_HOST | Host de PostgreSQL (p. ej., localhost o db.yourcompany.com) |
DB_PORT | Puerto de PostgreSQL (p. ej., 5432) |
DB_USER | Usuario de la base de datos (p. ej., postgres) |
DB_PASSWORD | Contraseña de la base de datos (p. ej., postgres) |
SECRET_KEY | Clave 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:
- Genera una clave nueva con
openssl rand -base64 32. - 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. - 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.
- Cuando todas las instancias funcionen con ese valor, define
SECRET_KEYcon 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.
| Variable | Descripción |
|---|---|
ROOT_EMAIL | Correo 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_ENDPOINT | URL 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_HOST | Host del servidor SMTP (p. ej., smtp.gmail.com) |
SMTP_PORT | Puerto del servidor SMTP (p. ej., 587 o 465) |
SMTP_USERNAME | Usuario SMTP (p. ej., noreply@yourcompany.com) |
SMTP_PASSWORD | Contraseña SMTP (p. ej., your_smtp_password) |
SMTP_FROM_EMAIL | Dirección del remitente (p. ej., noreply@yourcompany.com) |
SMTP_FROM_NAME | Nombre del remitente (p. ej., Your Company Name) |
SMTP_EHLO_HOSTNAME | Nombre 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
| Variable | Descripción | Valor por defecto |
|---|---|---|
| Configuración del servidor | ||
SERVER_PORT | Puerto en el que escucha el servidor (p. ej., 8080) | 8080 |
SERVER_HOST | Dirección del host a la que se vincula (p. ej., 0.0.0.0) | 0.0.0.0 |
CORS_ALLOW_ORIGIN | Orí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. | * |
ENVIRONMENT | Modo de entorno (p. ej., production) | production |
LOG_LEVEL | Nivel de registro (p. ej., debug o warn) | info |
| Configuración de la base de datos | ||
DB_PREFIX | Prefijo 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_NAME | Nombre de la base de datos (p. ej., notifuse_system) | ${DB_PREFIX}_system |
DB_SSLMODE | Modo SSL de la base de datos (p. ej., require o disable) | require |
DB_EXPECT_EXISTING | Con 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 nueva | false |
DB_MAX_CONNECTIONS | Máximo total de conexiones entre todas las bases de datos (p. ej., 100) | 100 |
DB_MAX_CONNECTIONS_PER_DB | Máximo de conexiones por base de datos de espacio de trabajo (p. ej., 3) | 3 |
DB_CONNECTION_MAX_LIFETIME | Duración máxima de una conexión (p. ej., 10m) | 10m |
DB_CONNECTION_MAX_IDLE_TIME | Tiempo máximo de inactividad antes de cerrar la conexión (p. ej., 5m) | 5m |
| Configuración del programador de tareas | ||
TASK_SCHEDULER_ENABLED | Activa el programador de tareas interno (p. ej., true o false) | true |
TASK_SCHEDULER_INTERVAL | Intervalo de ejecución de las tareas en segundos (p. ej., 30) | 30 |
TASK_SCHEDULER_MAX_TASKS | Máximo de tareas simultáneas (p. ej., 10) | 10 |
| Configuración de los envíos masivos | ||
BROADCAST_DATA_FEED_ALLOW_PRIVATE_HOSTS | Permite 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_CONCURRENCY | Correos 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_CONCURRENCY | Lo 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_HOSTS | Permite 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_KEY | Una clave de licencia autoalojada. Tiene prioridad sobre una clave pegada en la consola. No hace falta para usar Notifuse. | - |
| Privacidad | ||
TELEMETRY | Envía estadísticas de uso anónimas (p. ej., true o false) | true |
CHECK_FOR_UPDATES | Busca nuevas versiones (p. ej., true o false) | true |
| Configuración del puente SMTP | ||
SMTP_BRIDGE_ENABLED | Activa el servidor del puente SMTP para los correos transaccionales (p. ej., true o false) | false |
SMTP_BRIDGE_PORT | Puerto del puente SMTP (p. ej., 587 para STARTTLS, 465 para TLS implícito) | 587 |
SMTP_BRIDGE_DOMAIN | Nombre de dominio público del puente SMTP (p. ej., smtp.yourdomain.com) | localhost |
SMTP_BRIDGE_TLS | Modo TLS: starttls, implicit u off (ver más abajo). Se resuelve automáticamente si no se define. | auto |
SMTP_BRIDGE_TLS_CERT_BASE64 | Certificado TLS codificado en base64 (obligatorio para starttls e implicit) | - |
SMTP_BRIDGE_TLS_KEY_BASE64 | Clave privada TLS codificada en base64 (obligatoria para starttls e implicit) | - |
| Inicio de sesión único (OIDC) (consulta la guía de SSO) | ||
OIDC_ENABLED | Activa el inicio de sesión único mediante OpenID Connect (p. ej., true o false) | false |
OIDC_ISSUER_URL | URL del emisor del IdP, debe ser https (p. ej., https://accounts.google.com) | - |
OIDC_CLIENT_ID | Client ID OAuth2 de tu proveedor de identidad | - |
OIDC_CLIENT_SECRET | Client secret OAuth2 (se guarda cifrado y nunca se envía al navegador) | - |
OIDC_REDIRECT_URI | URL de callback registrada en el IdP. Se deriva de API_ENDPOINT si está vacía. | <API_ENDPOINT>/api/user.oidc.callback |
OIDC_SCOPES | Scopes separados por espacios (openid siempre se incluye) | openid email profile |
OIDC_BUTTON_LABEL | Texto del botón de inicio de sesión | Sign in with SSO |
OIDC_AUTO_CREATE_USERS | Crea cuentas automáticamente en el primer inicio de sesión SSO (requiere OIDC_ALLOWED_DOMAINS) | false |
OIDC_ALLOWED_DOMAINS | Lista de dominios de correo permitidos, separados por comas o punto y coma, que limita la creación automática | - |
| Configuración del tracing | ||
TRACING_ENABLED | Activa el tracing (p. ej., true) | false |
TRACING_SERVICE_NAME | Nombre del servicio para el tracing (p. ej., notifuse-production) | notifuse-api |
TRACING_SAMPLING_PROBABILITY | Probabilidad de muestreo (p. ej., 0.05) | 0.1 |
TRACING_TRACE_EXPORTER | Exportador de trazas: jaeger/zipkin/stackdriver/datadog/xray/none (p. ej., jaeger o datadog) | none |
TRACING_JAEGER_ENDPOINT | Endpoint de Jaeger (p. ej., http://jaeger:14268/api/traces) | http://localhost:14268/api/traces |
TRACING_ZIPKIN_ENDPOINT | Endpoint de Zipkin (p. ej., http://zipkin:9411/api/v2/spans) | http://localhost:9411/api/v2/spans |
TRACING_STACKDRIVER_PROJECT_ID | ID del proyecto de Stackdriver (p. ej., my-gcp-project-id) | - |
TRACING_AZURE_INSTRUMENTATION_KEY | Clave de instrumentación de Azure Monitor (p. ej., 12345678-1234-1234-1234-123456789012) | - |
TRACING_DATADOG_AGENT_ADDRESS | Dirección del agente de Datadog (p. ej., datadog-agent:8126) | localhost:8126 |
TRACING_DATADOG_API_KEY | Clave API de Datadog (p. ej., 1234567890abcdef1234567890abcdef) | - |
TRACING_XRAY_REGION | Región de AWS X-Ray (p. ej., us-east-1) | us-west-2 |
TRACING_AGENT_ENDPOINT | Endpoint general del agente (p. ej., monitoring-agent:8126) | localhost:8126 |
TRACING_METRICS_EXPORTER | Exportador de métricas: stackdriver/prometheus/datadog/none (p. ej., prometheus) | none |
TRACING_PROMETHEUS_PORT | Puerto 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:
| Modo | Descripción | Puerto habitual |
|---|---|---|
starttls | Escucha en texto plano. Los clientes deben pasar a TLS con STARTTLS antes de AUTH. Es el modo por defecto cuando se proporcionan certificados. | 587 |
implicit | TLS desde el primer byte (SMTPS). Necesario para los clientes que solo hablan TLS implícito. | 465 |
off | Sin 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.
