This is a NethServer 8 module for ntfy (https://ntfy.sh/).
ntfy (pronounced notify) is a simple HTTP-based pub-sub notification service. It allows you to send notifications to your phone or desktop via scripts from any computer, and/or using a REST API. It's infinitely flexible, and 100% free software.
The module provides a Traefik route, user/token/topic administration, an editor for the ntfy settings that keeps secrets out of the UI, backup and restore of the ntfy data, and outgoing mail through the NS8 smarthost.
Administration features adapted from Platypuschan/ns8-ntfy-reworked, GPL-3.0. See administration details.
Instantiate the module with:
add-module ghcr.io/geniusdynamics/ntfy:latest 1
The output of the command will return the instance name. Output example:
{"module_id": "ntfy1", "image_name": "ntfy", "image_url": "ghcr.io/geniusdynamics/ntfy:latest"}
Let's assume that the ntfy instance is named ntfy1.
Launch configure-module, by setting the following parameters:
host: a fully qualified domain name for the applicationhttp2https: enable or disable HTTP to HTTPS redirection (true/false)lets_encrypt: enable or disable Let's Encrypt certificate (true/false)server_config: optional, the editable ntfy settings as YAML (options); omitted, the current settings are keptios_push: optional, forward poll requests to ntfy.sh (or the previous upstream) for iOS instant notifications; omitted, the current state is keptupstream_access_token,web_push_public_key,web_push_private_key: optional secrets, stored instate/passwords.env(mode 0600); an empty value removes the secret, an omitted one keeps it
Example:
api-cli run configure-module --agent module/ntfy1 --data - <<EOF
{
"host": "ntfy.domain.com",
"http2https": true,
"lets_encrypt": false
}
EOF
The above command will:
- start and configure the ntfy instance
- configure a virtual host for Traefik to access the instance
A new instance starts with this server.yml: private topics (deny-all),
login enabled, signup disabled, a message cache and an attachment directory.
base-url: "https://ntfy.domain.com"
cache-file: "/var/lib/ntfy/cache.db"
attachment-cache-dir: "/var/lib/ntfy/attachments"
auth-file: "/var/lib/ntfy/auth.db"
auth-default-access: "deny-all"
enable-login: true
enable-signup: falseThe Settings page edits it under Advanced. It shows a filtered view of
state/config/server.yml: SMTP sender settings, upstream options, declarative
auth entries, private keys and other secrets are hidden and preserved when
saving, and cannot be added from the editor. listen-http, behind-proxy and
proxy-forwarded-header are enforced by the module, since ntfy is reached
only through Traefik. Duplicate keys, YAML aliases and merge keys are
rejected. Keep cache-file, auth-file, web-push-file and
attachment-cache-dir below /var/lib/ntfy, otherwise the data is neither
persistent nor backed up. Invalid ntfy option values are only detected by
ntfy itself: check the service log after changing advanced settings.
Configure from the command line with a local server.yml:
jq -n --arg host ntfy.domain.com --arg server_config "$(<server.yml)" \
'{host: $host, http2https: true, lets_encrypt: false, server_config: $server_config}' |
api-cli run configure-module --agent module/ntfy1 --data -The settings keys of older releases (base_url, auth_default_access,
enable_login, enable_signup, upstream_base_url,
web_push_email_address, cache_file, attachment_cache_dir, auth_file,
web_push_file) are still accepted and update the matching server.yml
options.
You can retrieve the configuration with
api-cli run get-configuration --agent module/ntfy1
It returns the route settings, the filtered server_config, ios_push and
auth_enabled. Secrets are never returned.
Open Users and tokens in the module UI. It lists users and roles, tokens
(label and expiry only) and topic permissions. It creates users with
generated passwords, generates replacement passwords, creates and revokes
tokens, and grants or removes topic permissions. A new password or token is
shown once, in the creation result. Existing passwords and tokens are never
returned. The last administrator cannot be deleted. Account changes briefly
restart ntfy. The page needs auth-file in server.yml.
The same actions are available from the command line:
api-cli run list-accounts --agent module/ntfy1
api-cli run manage-account --agent module/ntfy1 --data '{"operation":"add-user","username":"alice","role":"user"}'
api-cli run manage-account --agent module/ntfy1 --data '{"operation":"set-access","username":"alice","topic":"alerts","permission":"read-write"}'
api-cli run manage-account --agent module/ntfy1 --data '{"operation":"add-token","username":"alice","label":"monitoring","expires":"never"}'
Tokens inherit their user's permissions; an ntfy administrator can access all topics. Changing a password does not revoke existing tokens. NS8 keeps task results, so do not share the result of a creation task.
Generate a key pair inside the instance:
runagent -m ntfy1 podman exec ntfy-app ntfy webpush keys
Store the keys with configure-module (they go to state/passwords.env) and
set the public options in server_config:
api-cli run configure-module --agent module/ntfy1 --data - <<EOF
{
"host": "ntfy.domain.com",
"http2https": true,
"lets_encrypt": false,
"web_push_public_key": "<public key>",
"web_push_private_key": "<private key>"
}
EOF
web-push-file: "/var/lib/ntfy/webpush.db"
web-push-email-address: "admin@domain.com"ntfy data (message cache, users, tokens and ACLs, Web Push subscriptions and
attachments) is stored in the ntfy-app Podman volume, mounted at
/var/lib/ntfy. server.yml is mounted read-only at /etc/ntfy.
Before a module backup, ntfy is stopped for the time it takes to copy its
closed databases, attachments and server.yml into a snapshot directory
inside the volume; then it is started again and Restic uploads the snapshot.
The copy is removed after a successful backup. Allow free space in the volume
for a second copy of the databases.
Backups made by releases up to 1.x can be restored: they contain the settings and secrets, but no ntfy data, since those releases did not back it up.
Releases up to 1.x kept the settings in NTFY_* environment variables and the
ntfy data in the state directory. An update moves the settings to
state/config/server.yml, the secrets to state/passwords.env and the data to
the ntfy-app volume. Instances configured from the old Settings page could
not start ntfy (it rejects the empty auth-default-access they wrote); they
receive the settings of a new installation, with private topics: create users
and topic permissions in Users and tokens, or set
auth-default-access: read-write under Advanced for a public server. See
administration details.
ntfy migrates its message cache schema when it starts with a newer version, and an older ntfy cannot open the migrated cache. Create a module backup before updating; to roll back, restore the backup with the previous module version.
When the cluster smarthost is enabled, bin/discover-smarthost reads its host,
port, username and password from the local Redis replica before every start
and writes them to state/smarthost.env (mode 0600) as
NTFY_SMTP_SENDER_ADDR, NTFY_SMTP_SENDER_USER and NTFY_SMTP_SENDER_PASS.
The smarthost-changed event restarts ntfy, so changes apply without editing
server.yml. The sender address is smtp-sender-from from server.yml, an
email-shaped SMTP username, or no-reply@<host>.
If server.yml defines smtp-sender-addr, the NS8 smarthost is ignored.
ntfy supports plain SMTP and STARTTLS with certificate verification, not
implicit TLS (port 465): such a smarthost is skipped with a warning in the
service log.
To uninstall the instance:
remove-module --no-preserve ntfy1
Inspect the module environment, the containers and the ntfy log:
runagent -m ntfy1 env
runagent -m ntfy1 podman ps
runagent -m ntfy1 podman logs ntfy-app
runagent -m ntfy1 cat config/server.yml
Run a shell inside the container:
runagent -m ntfy1 podman exec -ti ntfy-app sh
Remove passwords, tokens and private keys before sharing configuration files or environment dumps.
The QEMU workflow (.github/workflows/test-module.yml) runs the Robot
Framework suite in tests/ on an NS8 node: the install leg installs the image
under test, the update leg installs release 1.0.0 and updates it.
The Python unit tests need PyYAML, which the NS8 agent provides:
python3 -m pip install PyYAML
python3 -m unittest discover -s tests -p 'test_*.py' -v
Set NTFY_TEST_BINARY to an ntfy executable of the pinned version to run the
account actions against a real ntfy as well. The browser-side YAML validation
has its own tests:
cd ui && yarn install && yarn test
Translated with Weblate.
To setup the translation process:
- add GitHub Weblate app to your repository
- add your repository to hosted.weblate.org or ask a nethserver developer to add it to ns8 Weblate project
Administration features (account and token management, the protected settings editor, backup snapshots, smarthost handling and their tests) are adapted from Platypuschan/ns8-ntfy-reworked, GPL-3.0.