ntfy

Self-hosted push notification service using simple HTTP pub-sub. Publish notifications from any script, CI pipeline, or monitoring system with a single curl command. Subscribe on Android, iOS, or the web. No signup, no cost, no third-party service — all traffic stays on your infrastructure.

Key Features

• HTTP pub-sub — publish via PUT/POST, subscribe via GET or WebSocket
• Mobile and web clients — Android, iOS apps and progressive web app
• Access control — per-topic user and permission management
• Attachment support — configurable file attachment size and expiry limits
• Abuse ban-feed — opt-in weighted offender feed for fail2ban or equivalent enforcement
• Behind-proxy mode — correct client IP identification via X-Forwarded-For
• Prometheus metrics — optional /metrics endpoint with ServiceMonitor support
• Persistent storage — PVC-backed SQLite cache and authentication databases
• PostgreSQL — external database URL loaded from a Kubernetes Secret
• External Secrets — optional credential reconciliation from provider-backed stores
• Gateway API — optional HTTPRoute rendering for modern ingress controllers
• Secure runtime — non-root execution, read-only root filesystem, dropped capabilities, seccomp, and no API token
• Production controls — resource bounds, bounded temporary storage, optional NetworkPolicy and PodDisruptionBudget
• S3 backup — optional scheduled archive of the ntfy data volume

Architecture and Boundaries

The chart runs one ntfy Deployment behind a ClusterIP Service. ntfy listens on the configurable containerPorts.http port (2586 by default), while service.port remains the stable client-facing port. The ConfigMap is mounted read-only at /etc/ntfy; /tmp is a bounded emptyDir; and /var/cache/ntfy is backed by a PVC or a bounded ephemeral volume.

SQLite is the default store. PostgreSQL can come from the HelmForge subchart or an external service, but it does not make this single-replica chart highly available and does not provide shared attachment storage. Ingress and Gateway API are optional edge routes. The chart does not install an edge controller, cert-manager, Prometheus Operator, External Secrets Operator, an SMTP server, an OIDC provider, or an S3 service.

Installation

HTTPS repository:

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install ntfy helmforge/ntfy

OCI registry:

helm install ntfy oci://ghcr.io/helmforgedev/helm/ntfy

Upgrade guidance

The current chart defaults to ntfy 2.32.0. The chart remains single-replica because upstream clustering and local attachment sharing are outside its production boundary. Back up persistent state and any PostgreSQL database, then validate publishing, cache replay, authentication, email delivery, web push, and attachment workflows. Existing values remain compatible. The --reset-then-reuse-values flag retains an explicit image.tag from the current release; remove or update that override if you want to adopt the chart’s v2.32.0 default. Review the 2.32.0 release:

helm upgrade ntfy helmforge/ntfy \
  --reset-then-reuse-values

ntfy 2.31.1 migrated the message database schema from version 16 to 17. After upgrading an instance from ntfy 2.30.0 or earlier to 2.32.0, rolling back to 2.31.0 or earlier requires manually resetting the recorded message schema version before starting the older server. For PostgreSQL, run UPDATE schema_version SET version = 16 WHERE store = 'message';. For the SQLite cache file, run UPDATE schemaVersion SET version = 16 WHERE id = 1;. Rolling back to 2.31.1 or later does not require this adjustment because those releases tolerate newer message schemas. Review the upstream 2.31.1 migration and rollback notes before downgrading.

Deployment Examples

# values.yaml — ntfy with ingress, behind Traefik
ntfy:
  baseUrl: 'https://ntfy.example.com'
  behindProxy: true

persistence:
  enabled: true
  size: 2Gi

ingress:
  enabled: true
  ingressClassName: traefik
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: ntfy.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: ntfy-tls
      hosts:
        - ntfy.example.com

curl -d "Hello from Kubernetes!" https://ntfy.example.com/my-topic

# values.yaml — ntfy with authentication enabled (deny anonymous access)
ntfy:
  baseUrl: 'https://ntfy.example.com'
  behindProxy: true
  authDefaultAccess: deny-all
  extraConfig: |
    auth-file: /var/cache/ntfy/user.db

persistence:
  enabled: true
  size: 2Gi

ingress:
  enabled: true
  ingressClassName: traefik
  hosts:
    - host: ntfy.example.com
      paths:
        - path: /
          pathType: Prefix

# Create an admin user
kubectl exec -it deployment/ntfy -- ntfy user add --role=admin admin

# Publish with authentication
curl -u admin:password -d "Secure notification" https://ntfy.example.com/my-topic

# values.yaml — ntfy with file attachment support
ntfy:
  baseUrl: 'https://ntfy.example.com'
  behindProxy: true
  attachmentTotalSizeLimit: '200M'
  attachmentFileSizeLimit: '20M'
  attachmentExpiryDuration: '24h'

persistence:
  enabled: true
  # Increase PVC size to accommodate attachments
  size: 10Gi

ingress:
  enabled: true
  ingressClassName: traefik
  hosts:
    - host: ntfy.example.com
      paths:
        - path: /
          pathType: Prefix

# values.yaml — emit abusive visitors for an external fail2ban consumer
ntfy:
  banFeed:
    enabled: true
    file: /var/cache/ntfy/ban.log
    window: 10m
    threshold: 100
    weights:
      - '42909:10'

# values.yaml — PostgreSQL URL from a provider-managed Secret
ntfy:
  authDefaultAccess: deny-all
  database:
    enabled: true
    existingSecret: ntfy-database
    existingSecretKey: database-url

persistence:
  enabled: false

externalSecrets:
  enabled: true
  items:
    - fullnameOverride: ntfy-database
      spec:
        secretStoreRef:
          name: production-secrets
          kind: ClusterSecretStore
        target:
          name: ntfy-database
        data:
          - secretKey: database-url
            remoteRef:
              key: ntfy/database
              property: url

# values.yaml — ntfy with Prometheus metrics
ntfy:
  baseUrl: 'https://ntfy.example.com'
  enableMetrics: true
  # Expose metrics on a separate port to avoid routing /metrics via Ingress
  metricsListenHttp: ':9090'

persistence:
  enabled: true
  size: 2Gi

metrics:
  serviceMonitor:
    enabled: true
    interval: 30s

ingress:
  enabled: true
  ingressClassName: traefik
  hosts:
    - host: ntfy.example.com
      paths:
        - path: /
          pathType: Prefix

# values.yaml — ntfy exposed with Gateway API
ntfy:
  baseUrl: 'https://ntfy.example.com'
  behindProxy: true

persistence:
  enabled: true
  size: 2Gi

gateway:
  enabled: true
  parentRefs:
    - name: public
      namespace: gateway-system
  hostnames:
    - ntfy.example.com

Configuration Reference

Core

Image

ntfy Configuration

The listener is controlled only by containerPorts.http; attempts to override listen-http through extraConfig or NTFY_LISTEN_HTTP through extraEnv are rejected so the process, Service, and probes remain aligned.

External Secrets

Each item supports name, fullnameOverride, labels, annotations, and a complete ExternalSecret spec. Configure either spec.secretStoreRef or a per-source sourceRef. The target Secret name must match ntfy.database.existingSecret. See the External Secrets Operator documentation for provider configuration.

Persistence

By default, ntfy stores its SQLite cache and authentication databases in /var/cache/ntfy. Persistence survives pod restarts. With PostgreSQL, the PVC may be disabled only when attachments, the ban-feed, and custom file-backed options do not require durable local storage.

Service

Ingress

Gateway API

Probes

Probes use the /v1/health endpoint.

Metrics

Resources and Security

Service Account

Runtime Security and Availability

The defaults run as UID/GID 1000 with RuntimeDefault seccomp, a read-only root filesystem, no privilege escalation, and all capabilities dropped. CPU and memory requests and limits are set by default; tune them from observed usage.

Network Policy

Ingress isolation can be enabled independently. When egress isolation is enabled, list every external dependency. External PostgreSQL requires an explicit database CIDR; SMTP, OIDC, web push, and S3 need suitable extraEgress rules.

Backup

The optional CronJob archives /var/cache/ntfy and uploads it to S3-compatible storage. It requires persistent storage and does not dump PostgreSQL. Use an existing Secret containing access-key and secret-key in production.

OpenID Connect and SMTP

OIDC client secrets and SMTP passwords are injected from Secrets through environment variables and never written to the ConfigMap. Restart the Deployment after rotating an existing Secret.

Scheduling

Extra

Common Issues

curl -d "Test notification from Kubernetes" https://ntfy.example.com/test-topic

More Information

• ntfy Official Website
• ntfy Documentation
• ntfy GitHub Repository
• HelmForge ntfy Chart Source