ntfy Docker Compose: Notificaciones Push Self-Hosted 2026

ntfy Docker Compose es la forma más sencilla de montar tu propio servidor de notificaciones push self-hosted en minutos. Con esta solución envías alertas a tu móvil o escritorio desde cualquier script, contenedor o servicio mediante una simple petición HTTP, sin depender de Firebase, sin cuentas de terceros y sin pagar suscripciones. En esta guía aprenderás a desplegarlo, asegurarlo con autenticación y conectarlo con el resto de tu homelab.

¿Qué es ntfy y por qué usar ntfy Docker Compose?

ntfy (se pronuncia notify) es un servidor de notificaciones push pub-sub basado en HTTP y de código abierto. La idea es deliberadamente simple: publicas un mensaje en un «tema» (topic) con una petición POST o PUT, y cualquier dispositivo suscrito a ese tema lo recibe al instante. No necesitas SDK, ni claves de API complejas, ni registrarte en ningún servicio externo.

Aunque existe la instancia pública gratuita ntfy.sh, alojar tu propia instancia con ntfy Docker Compose te aporta privacidad total (tus alertas no pasan por servidores ajenos), control de acceso a medida y límites de uso que decides tú. Desplegar ntfy Docker Compose es, además, reversible y desechable: todo vive en un par de ficheros y un volumen. Estos son los casos de uso más habituales:

• Alertas de infraestructura: avisos de copias de seguridad, espacio en disco, caídas de servicios o reinicios.
• Notificaciones de contenedores: integración con monitores como Uptime Kuma para monitorizar tus servicios o avisos de actualizaciones con Watchtower al actualizar contenedores.
• Automatización del hogar: mensajes desde Home Assistant y tus automatizaciones domóticas.
• Scripts personales: que un cron te avise cuando termina una tarea larga.

Frente a alternativas como Gotify o Pushover, ntfy destaca por su app móvil pulida, su soporte de UnifiedPush en Android y su capacidad de funcionar tanto desde la línea de comandos como desde la interfaz web. Por eso desplegarlo con Docker Compose se ha convertido en una de las incorporaciones más prácticas para cualquier homelab moderno.

Requisitos previos para desplegar ntfy Docker Compose

Antes de empezar con la instalación de ntfy Docker Compose, asegúrate de cumplir estos requisitos mínimos. El servicio es extremadamente ligero, así que funciona sin problemas incluso en una Raspberry Pi o en un VPS modesto.

• Un servidor Linux (Debian, Ubuntu, etc.) con Docker Engine y el plugin Docker Compose v2 instalados.
• Acceso por terminal con un usuario en el grupo docker o con privilegios sudo.
• Unos 256 MB de RAM libres (consume mucho menos en reposo) y espacio en disco para la caché de mensajes.
• Opcional pero recomendado: un dominio o subdominio (por ejemplo ntfy.tudominio.com) y un proxy inverso con HTTPS para exponerlo de forma segura.

Si todavía no tienes un proxy inverso configurado, te resultará útil revisar nuestra guía de Caddy con HTTPS automático o la de Nginx Proxy Manager para gestionar dominios y SSL, ya que más adelante publicaremos el servicio detrás de uno de ellos.

Instalación paso a paso de ntfy Docker Compose

Vamos a crear la estructura de carpetas, el fichero de configuración y el stack de contenedores. Empieza creando un directorio de trabajo y las carpetas que montaremos como volúmenes persistentes para la configuración y la caché.

mkdir -p ~/docker/ntfy/etc ~/docker/ntfy/cache
cd ~/docker/ntfy

El comando anterior prepara dos directorios: etc guardará el server.yml y la base de datos de usuarios, y cache almacenará los mensajes en cola. Ahora crea el fichero docker-compose.yml con el siguiente contenido.

services:
  ntfy:
    image: binwiederhier/ntfy:v2.25.0
    container_name: ntfy
    command: serve
    environment:
      - TZ=Europe/Madrid
    volumes:
      - ./etc:/etc/ntfy
      - ./cache:/var/cache/ntfy
    ports:
      - "8080:80"
    healthcheck:
      test: ["CMD-SHELL", "wget -q --tries=1 http://localhost:80/v1/health -O - | grep -Eo '\"healthy\"\\s*:\\s*true' || exit 1"]
      interval: 60s
      timeout: 10s
      retries: 3
      start_period: 40s
    restart: unless-stopped

Hemos fijado la versión v2.25.0 en lugar de latest para evitar sorpresas en futuras actualizaciones, y publicamos el contenedor en el puerto 8080 del host (internamente ntfy escucha en el 80). Antes de levantarlo, necesitamos su archivo de configuración: crea etc/server.yml con un contenido inicial mínimo.

# etc/server.yml
base-url: "https://ntfy.tudominio.com"
listen-http: ":80"
cache-file: "/var/cache/ntfy/cache.db"
attachment-cache-dir: "/var/cache/ntfy/attachments"
auth-file: "/etc/ntfy/user.db"
auth-default-access: "deny-all"
behind-proxy: true

La clave aquí es auth-default-access: "deny-all": con ella, nadie podrá leer ni publicar en tus temas sin estar autenticado, lo que convierte tu servidor en privado por defecto. Con la configuración lista, levanta el stack y comprueba que arranca correctamente.

docker compose up -d
docker compose logs -f ntfy

Si todo va bien, en los logs verás una línea indicando que ntfy está sirviendo en el puerto 80. Visita http://IP-DEL-SERVIDOR:8080 en tu navegador y deberías ver la interfaz web. Con esto, la base de tu despliegue de ntfy Docker Compose ya está funcionando; ahora toca asegurarlo.

Configurar autenticación y control de acceso en ntfy Docker Compose

Como hemos puesto deny-all, el siguiente paso es crear usuarios y asignar permisos sobre los temas. Todas las operaciones se hacen con la CLI integrada, ejecutándola dentro del contenedor. Empieza creando un usuario administrador.

docker compose exec ntfy ntfy user add --role=admin admin
docker compose exec ntfy ntfy user add alertas

El primer comando crea un usuario admin con acceso de lectura y escritura a todos los temas; el segundo crea un usuario normal llamado alertas sin permisos hasta que se los concedas. Cada comando te pedirá una contraseña de forma interactiva. A continuación, define qué puede hacer el usuario normal mediante la lista de control de acceso.

# El usuario "alertas" puede leer y escribir en el tema "servidores"
docker compose exec ntfy ntfy access alertas servidores rw

# Permitir solo lectura en temas que empiecen por "backups"
docker compose exec ntfy ntfy access alertas "backups*" read-only

# Revisar la configuración de permisos actual
docker compose exec ntfy ntfy access

Los permisos disponibles son read-write (rw), read-only (ro), write-only (wo) y deny. Esta granularidad es uno de los grandes puntos fuertes de gestionar la autenticación con ntfy Docker Compose: puedes tener tokens que solo publican alertas y dispositivos que solo las leen, reduciendo el riesgo si una credencial se filtra.

Enviar notificaciones: ejemplos prácticos con curl y scripts

La gracia de ntfy es lo fácil que resulta publicar. Una notificación básica es tan simple como una petición POST con curl, indicando usuario y contraseña (o token) porque hemos activado la autenticación.

curl -u alertas:tu-contraseña \
  -d "La copia de seguridad nocturna ha finalizado correctamente" \
  https://ntfy.tudominio.com/servidores

Ese mensaje llegará al instante a todos los dispositivos suscritos al tema servidores. Esta sencillez es la razón por la que ntfy Docker Compose encaja tan bien en cualquier flujo de automatización. Pero ntfy permite mucho más: títulos, prioridades, etiquetas con emojis e incluso abrir una URL al pulsar la notificación, todo mediante cabeceras HTTP. Veamos un ejemplo más completo para una alerta crítica.

curl -u alertas:tu-contraseña \
  -H "X-Title: Disco casi lleno" \
  -H "X-Priority: 5" \
  -H "X-Tags: warning,floppy_disk" \
  -H "X-Click: https://grafana.tudominio.com" \
  -d "El volumen /var supera el 90% de uso" \
  https://ntfy.tudominio.com/servidores

Aquí X-Priority: 5 marca la alerta como urgente (vibra y suena aunque el móvil esté en silencio según la configuración), X-Tags añade un icono de aviso y X-Click abre tu panel de Grafana al tocar el mensaje. Estas cabeceras hacen que integrar el servidor en cualquier script de Bash, tarea de cron o contenedor sea cuestión de una línea.

HTTPS y proxy inverso para ntfy Docker Compose

Para recibir notificaciones desde fuera de tu red local —y para que la app de iOS funcione— necesitas exponer el servicio con HTTPS a través de un proxy inverso. Recuerda que en el server.yml ya activamos behind-proxy: true, imprescindible para que el límite de peticiones cuente las IP reales y no la del proxy.

Si usas Caddy, basta con añadir un bloque que apunte al puerto que publicamos antes. Este fragmento se coloca en tu Caddyfile, en la máquina donde corre el proxy.

ntfy.tudominio.com {
    reverse_proxy localhost:8080
}

Caddy gestionará automáticamente el certificado TLS de Let’s Encrypt, de modo que https://ntfy.tudominio.com quedará accesible y cifrado. Tras recargar el proxy, abre esa URL: deberías ver la interfaz web servida ya por HTTPS. Con esto, tu instancia de ntfy Docker Compose está lista para recibir y enviar avisos desde cualquier lugar de forma segura.

Para automatizaciones internas entre contenedores, lo más limpio es conectar ntfy a la misma red Docker que tus otros servicios y referenciarlo por su nombre (http://ntfy:80), evitando salir a Internet para una notificación que se queda en casa.

Notificaciones en iOS, Android y UnifiedPush

Una vez publicado con HTTPS, instala la app de ntfy (disponible en Google Play, F-Droid y la App Store), añade tu servidor en los ajustes con su URL y tus credenciales, y suscríbete a un tema. En Android, ntfy puede actuar como distribuidor de UnifiedPush, lo que permite que otras apps compatibles reciban push a través de tu propio servidor sin Google.

En iOS hay un matiz importante por las restricciones de Apple: para recibir notificaciones instantáneas, tu instancia debe reenviar las peticiones de sondeo a un servidor superior. Esto se configura en el server.yml añadiendo la siguiente opción.

# Necesario para notificaciones instantáneas en iOS
upstream-base-url: "https://ntfy.sh"

Con esta línea, tu servidor envía a ntfy.sh únicamente un identificador de mensaje (nunca el contenido), y la app de iOS recupera el mensaje real directamente de tu instancia. Así, tu despliegue de ntfy Docker Compose mantiene la privacidad del contenido mientras esquiva las limitaciones del sistema de notificaciones de Apple. Recuerda reiniciar el contenedor con docker compose restart ntfy tras cualquier cambio en la configuración.

Solución de problemas frecuentes en ntfy Docker Compose

Estos son los errores más habituales al desplegar ntfy Docker Compose y cómo resolverlos rápidamente.

• 403 Forbidden al publicar: con deny-all activo es normal; revisa que el usuario tiene permiso rw sobre el tema con ntfy access y que envías las credenciales.
• El contenedor no arranca: casi siempre es un error de sintaxis en server.yml (YAML es sensible a la indentación). Mira docker compose logs ntfy para ver la línea exacta.
• Todas las peticiones cuentan como un único visitante: falta behind-proxy: true o el proxy no envía la cabecera X-Forwarded-For.
• iOS no recibe nada en segundo plano: comprueba que has definido upstream-base-url y que el dominio es accesible por HTTPS desde Internet.

Para escenarios de mucho tráfico, revisa además las opciones visitor-request-limit-burst y visitor-message-daily-limit en la documentación oficial de configuración de ntfy, que te permiten ajustar los límites por IP a tus necesidades.

Conclusión

Montar ntfy Docker Compose es una de esas mejoras que, con apenas un par de ficheros, transforma cómo gestionas tu infraestructura: dejas de depender de servicios externos y pasas a recibir alertas privadas, instantáneas y totalmente bajo tu control. Hemos cubierto la instalación, la autenticación con ACL, el envío de notificaciones enriquecidas, la publicación con HTTPS y el soporte para iOS y Android.

El siguiente paso natural es integrar tu ntfy Docker Compose con el resto de tu stack: conéctalo a tus monitores, a tus scripts de copias de seguridad y a tu automatización del hogar. Si quieres seguir ampliando tu servidor, explora más guías en nuestra categoría de tutoriales de Docker Compose.

Preguntas frecuentes (FAQ)

¿Es gratis usar ntfy self-hosted?

Sí. ntfy es software de código abierto bajo licencia Apache 2.0 y GPLv2, y alojarlo tú mismo no tiene coste de licencia. Solo pagas el servidor o VPS donde lo ejecutes, que puede ser una Raspberry Pi por lo ligero que es.

¿Necesito un dominio para recibir notificaciones en el móvil?

Para uso solo en red local puedes conectarte por IP a tu ntfy Docker Compose, pero para recibir avisos desde fuera y para que iOS funcione correctamente conviene un dominio con HTTPS a través de un proxy inverso como Caddy o Traefik.

¿Cómo envío notificaciones desde un contenedor Docker?

Conecta el contenedor a la misma red que ntfy y haz una petición con curl o con la librería HTTP de tu lenguaje a http://ntfy:80/tu-tema, incluyendo las credenciales o un token de acceso.

¿Cuál es la diferencia entre ntfy y Gotify?

Ambos son servidores de notificaciones self-hosted, pero ntfy usa un modelo de temas abierto, ofrece soporte de UnifiedPush y reenvío para iOS, y permite publicar sin crear apps previamente, lo que lo hace más flexible para scripts y automatización.

¿Puedo usar tokens en lugar de contraseñas?

Sí, y es lo recomendable para automatización. Genera un token con ntfy token add usuario; los tokens empiezan por tk_ y se envían en la cabecera Authorization: Bearer, evitando exponer tu contraseña en scripts.

Fuentes y recursos oficiales

• Sitio oficial de ntfy
• Documentación oficial de ntfy
• Repositorio de ntfy en GitHub
• Documentación oficial de Docker Compose
• Proyecto UnifiedPush