ntfy on AWS User Guide

Overview

This image runs ntfy (pronounced notify), the open source, self-hosted pub/sub notification service - publish a message to a topic with a single HTTP POST from any script, server or application, and receive it in real time in the web app, the Android and iOS apps, or any subscriber. A privacy-respecting alternative to hosted push services, deployable in your own VPC.

The ntfy server is a single Go binary that serves both the REST API and the bundled web app. It runs behind nginx as a reverse proxy. The datastore is an embedded SQLite database for accounts and the message cache. The server listens on 127.0.0.1:2586 and is reached through nginx on port 80 (and 443 once you add TLS).

Access control defaults to deny-all, so only authenticated users can read or publish. On the first boot of every deployed instance, a one-shot service recreates an empty authentication database and creates a single administrator account with a per-instance password. The login is written to /root/ntfy-credentials.txt with mode 0600.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and inbound ports 80 and 443 from the networks your users and publishers will reach ntfy on
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for ntfy. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of t3.small or larger - ntfy is lightweight. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that allows inbound port 22 from your management network and inbound ports 80 and 443 from the networks your users use. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation takes under a minute after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg ntfy Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22, 80, and 443 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type t3.small \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":30,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=ntfy-01}]'

The command prints a JSON document on success. Note the instance ID, then retrieve its public address once it is running with aws ec2 describe-instances --instance-ids <instance-id> --query "Reservations[].Instances[].PublicIpAddress" --output text.

Step 3: Connect and Retrieve the Administrator Login

Connect over SSH with the key pair you selected and the public IP address from step 2. The SSH login user depends on the operating system of the AMI variant you launched:

The first boot service runs before the SSH daemon becomes ready, so the credentials file is always in place when you log in for the first time.

ssh <login-user>@<public-ip>
sudo cat /root/ntfy-credentials.txt

You will see a plain text file containing the ntfy URL, the administrator username (admin) and the password. From the same SSH session you can confirm the deployment is healthy - the health endpoint is open:

curl -fsS http://127.0.0.1/v1/health

{"healthy":true}

A "healthy":true response confirms the full stack - nginx and the ntfy server - is serving.

Step 4: First Sign-in

Open a web browser and navigate to http://<public-ip>/. ntfy presents its web app. Select Sign in (top right) and enter the username admin and the password from /root/ntfy-credentials.txt.

The ntfy web app - subscribe to topics and read notifications in the browser.

Step 5: Publish to a Topic

In ntfy, a topic is just a name - publish to it and any subscriber receives the message. Because access control is deny-all, authenticate with your administrator credentials (or an access token). Publish a message with a single HTTP call - from a script, a cron job, a monitoring tool, anything:

curl -u admin:<password> \
  -H "Title: Backup complete" \
  -H "Priority: high" \
  -H "Tags: white_check_mark" \
  -d "Database dump 4.2 GB written to S3 successfully" \
  http://<public-ip>/alerts

Subscribe to the alerts topic in the web app and the message appears instantly, with its title, tags and priority.

A ntfy topic receiving messages published over the REST API, with titles, tags and priorities.

Step 6: Settings, Tokens and Mobile Apps

Open Settings to manage your account, notification preferences and subscriptions. Create access tokens (under your account) so scripts can publish without your password. Install the official ntfy Android or iOS app, add your server http://<public-ip>/ (or your HTTPS domain), sign in, and subscribe to topics to receive push notifications on your phone.

ntfy settings - account, notification preferences and subscriptions.

Step 7: Access Control

Access defaults to deny-all. Manage users and per-topic access from the command line (run these over SSH on the instance):

• List users: sudo ntfy user list
• Add a user (you will be prompted for a password): sudo ntfy user add <username>
• Grant read/write on a topic: sudo ntfy access <username> <topic> rw
• Make one topic publicly readable: sudo ntfy access everyone <public-topic> ro

This lets you keep most topics private while exposing selected ones, or give each team its own credentials. See https://docs.ntfy.sh/config/#access-control for the full model.

Step 8: Enable HTTPS with Let's Encrypt

For any production deployment serve ntfy over HTTPS so logins and tokens cannot be intercepted (and browser push notifications work, which require HTTPS). The image ships with nginx, which certbot can configure automatically.

The following assumes you have a DNS record pointing your fully qualified domain name at the instance's public IP address.

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d ntfy.your-domain.example \
  --non-interactive --agree-tos -m you@your-domain.example \
  --redirect

After certbot finishes, set the base URL so generated links are correct, then restart ntfy:

sudo sed -i 's|^base-url: .*|base-url: "https://ntfy.your-domain.example"|' /etc/ntfy/server.yml
sudo systemctl restart ntfy

Step 9: Backups and Maintenance

ntfy keeps its accounts, access control and message cache under /var/lib/ntfy (SQLite databases). Back it up regularly:

sudo systemctl stop ntfy
sudo tar czf <backup-dir>/ntfy-data-$(date +%F).tgz -C /var/lib/ntfy .
sudo systemctl start ntfy

Ship the archive to an Amazon S3 bucket or another object store. Because the data directory is on its own EBS volume, you can also take coordinated EBS snapshots. To upgrade ntfy, replace /usr/local/bin/ntfy with a newer release and restart. See https://docs.ntfy.sh/.

Step 10: Scaling and Operations

• Use access tokens for scripts and CI rather than the admin password
• Integrate ntfy with monitoring (Grafana, Prometheus Alertmanager), backups and cron jobs by publishing to topics
• Put the web tier behind an Application Load Balancer (with websocket support) if you need high availability

Each of these is documented in the official ntfy documentation at https://docs.ntfy.sh/.

Support

cloudimg provides 24/7/365 expert technical support for this image. Guaranteed response within 24 hours, one hour average for critical issues. Contact support@cloudimg.co.uk.

For general ntfy questions consult the documentation at https://docs.ntfy.sh/. ntfy is a trademark of its respective owner; use here is nominative and does not imply affiliation or endorsement.