> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Instalación autoalojada

> Cómo autoalojar Notifuse

> [!TIP]
>
> **¿Buscas una solución gestionada?** [Notifuse Cloud](https://cloud.notifuse.com) 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](https://www.notifuse.com/docs/assets/screenshots/setup.png)

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

### 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`).

> [!WARNING]
>
> 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](#upgrading-a-docker-compose-installation)). 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](#replacing-the-secret-key) indica ese valor por defecto y el cambio que hay que hacer.

```bash
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](#environment-variables) 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.

> [!WARNING]
>
> 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](https://github.com/Notifuse/notifuse/blob/main/CHANGELOG.md) entre tu versión y la nueva, [haz una copia de seguridad](https://www.notifuse.com/es/docs/self-hosting/backups.md), 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](https://www.notifuse.com/es/docs/self-hosting/upgrading-postgresql.md) 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:

```bash
# 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](#environment-variables).

### 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](https://www.notifuse.com/es/docs/features/templates.md#view-in-browser) 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.

> [!WARNING]
>
> **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:
>
> ```bash
> # ✅ 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:**

```bash
openssl rand -base64 32
```

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

> [!WARNING]
>
> 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](#replacing-the-secret-key).

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

> [!WARNING]
>
> 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:
>
> ```bash
> # 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](https://www.notifuse.com/es/docs/self-hosting/changing-domain.md).                                                          |
| `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`.                                                                                       |

> [!NOTE]
>
> **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](https://www.notifuse.com/es/docs/features/broadcast-campaigns.md) 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](https://www.notifuse.com/es/docs/features/broadcast-campaigns.md#sending-speed).                                                                                                                                                                                                                                                                                                                   | `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](https://www.notifuse.com/es/docs/features/webhooks.md) y [nodos webhook de las automatizaciones](https://www.notifuse.com/es/docs/features/automations.md#webhook-node)) 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](https://www.notifuse.com/es/docs/self-hosting/licence.md) 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](https://www.notifuse.com/es/docs/self-hosting/sso.md)) |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |                                         |
| `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](https://www.notifuse.com/es/docs/features/transactional-api.md#smtp-bridge) 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.

> [!WARNING]
>
> 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

```bash
# 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.

```bash
# 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:

```bash
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:

```bash
# 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`:

```bash
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>"
```

> [!NOTE]
>
> 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:

```bash
# 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.

```bash
#!/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.

> [!WARNING]
>
> 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](https://cloud.notifuse.com).

- [PikaPods](https://www.pikapods.com/pods?run=notifuse)
- [RepoCloud](https://repocloud.io/details/Notifuse/?ref=67eysha)
- [Sealos](https://sealos.io/products/app-store/notifuse)
- [Northflank](https://northflank.com/stacks/deploy-notifuse)
