ntfy

Send notifications to your phone and browser.

Choose your deployment and the way you want to use Selfhost. The instructions below follow that choice.

Deployment Use Selfhost with

Set up ntfy

Editable Compose files in your own directory.

Start ntfy, then run Create user and explicitly choose admin for the first trusted administrator.
Grant each ordinary user access only to the topic patterns they need.

selfhost app --directory ./ntfy init ntfy

Initialization writes portable files and does not start the app. Review compose.yaml, the private .env and any files in files/, then start it:

selfhost app --directory ./ntfy start

No Selfhost dashboard or background service is needed. You can also start these files directly:

cd ntfy
docker compose -f compose.yaml up -d

Connect an existing installation

Use Existing apps → Link an app in the dashboard, or the CLI’s existing-app commands. Choose ntfy, its URL and, optionally, its exact Docker container on a connected server.

Save existing.json with your app URL. Add server_id and container for container inspection and actions.

{
  "profile": "ntfy",
  "name": "ntfy",
  "url": "https://app.example.com"
}

selfhost existing link --file existing.json
selfhost existing list
selfhost existing inspect EXISTING_ID

Linking enables the existing-app profile’s supported inspection and actions. It does not import Compose or attach the new-deployment settings and onboarding profiles described below.

Existing app commands, permissions and unlinking

Before configuring integrations

New recipes deny anonymous topic access. Repeating Create user does not reset an existing account.
Set the public base URL before enabling attachments; use /var/cache/ntfy/attachments for persistent attachments.
An OIDC login contract is not assumed. ntfy users, tokens and topic ACLs remain its native access system.

ntfy integrations

Compose service: ntfy. These operations use the profile saved when this deployment is created.

Native settings

Changes use the app’s Compose environment. Unrelated settings are preserved.

Supported fields (11)

Public URL base-url: string
Default topic access default-access: Use deny-all for private notifications. Explicit access rules can permit selected topics. stringChoices: deny-all, read-only, write-only, read-write
Enable login login: stringChoices: true, false
Require web login require-login: stringChoices: true, false
Allow registration signup: stringChoices: true, false
Message retention cache-duration: Duration such as 12h or 7d. string
Attachment retention attachment-duration: Duration such as 3h or 24h. string
Use proxy forwarding headers behind-proxy: Only enable when the trusted proxy replaces incoming forwarding headers. stringChoices: true, false
Trusted proxy addresses trusted-proxies: Comma-separated addresses or CIDRs. Avoid trusting arbitrary clients. string
iOS notification relay upstream-url: Optional relay, such as https://ntfy.sh. Enables wake-up requests via that service. string
Attachment cache directory attachment-directory: Set the public base URL first. Use /var/cache/ntfy/attachments to keep attachments in the persistent volume. string

Save a JSON map of the field IDs you want to change as changes.json. Replace FIELD_ID with an ID from the supported fields above, and use its declared value type. Review the plan and replace REVIEWED_REVISION with the revision it returns.

{
  "FIELD_ID": "YOUR_VALUE"
}

selfhost app --directory ./ntfy config ntfy
selfhost app --directory ./ntfy plan ntfy changes.json
selfhost app --directory ./ntfy apply ntfy changes.json --revision REVIEWED_REVISION

Saved changes need service recreation to become active. Existing interpolated environment values stay under your control in .env or Compose.

Database placement

This recipe supports postgres. Workspace projects can choose a dedicated database, a shared source with a separate database and account, or an existing external database before their first start.

Standalone directories use the generated Compose and environment files directly. Configure the database there before first start. Selfhost’s source provisioning commands belong to workspace projects and are optional.

Database setup, CLI commands and backups

App actions

List users · schedulable

Read users and assigned roles.

selfhost app --directory ./ntfy action ntfy list-users

A workspace can schedule this workflow while Selfhost runs. A standalone user can invoke it through an external scheduler. Scheduling guide.

List topic permissions · schedulable

Read configured topic permissions.

selfhost app --directory ./ntfy action ntfy list-access

A workspace can schedule this workflow while Selfhost runs. A standalone user can invoke it through an external scheduler. Scheduling guide.

Create user

Add a user without changing an existing account. Select admin only for a trusted administrator.

Username username: stringLength: 1 to 64 characters
Password password: secretLength: 12 to unbounded characters
Role role: stringChoices: user, adminDefault: "user"

Save the input IDs and selected values in a private action-inputs.json file.

selfhost app --directory ./ntfy action ntfy create-user --inputs action-inputs.json

Set topic permission

Apply an explicit permission for one user and topic pattern. Review wildcards carefully.

Username username: stringLength: 1 to unbounded characters
Topic or pattern topic: stringLength: 1 to unbounded characters
Permission permission: stringChoices: read-write, read-only, write-only, deny-all

Save the input IDs and selected values in a private action-inputs.json file.

selfhost app --directory ./ntfy action ntfy topic-access --inputs action-inputs.json

App configuration reference

Versions and updates

This deployment uses the following images. Existing projects retain their saved recipe and images. A new catalogue version does not silently update them.

ntfy: binwiederhier/ntfy:v2.28.0

Review compatibility and back up app data before an update. Choose an image version and review the change.

Keep control of your setup

Selfhost remains optional. Your app runs using ordinary Compose files, its own settings and persistent data. Keep the Compose project name and volumes to preserve storage. Configuration exports and setting backups do not include application data.

Standalone CLI guide · Backups and removal · ntfy documentation