Self-hosting ntfy on Fly.io, from deploy to your first alert
Run your own ntfy server on Fly.io: a two-file deploy, one volume, one machine that never sleeps, accounts and topics over SSH, your phone subscribed, and Butters pointed at it.
ntfy is a small open source server that turns an HTTP request into a notification on your phone. The public server at ntfy.sh is free and works well. But it's someone else's server, and on it, anyone who guesses your topic name can read your alerts.
We've already covered hosting it on Coolify . If you'd rather not run a server at all, Fly.io is a good fit. ntfy is one small Go binary with a SQLite file, and Fly runs that on its smallest machine without complaint. This post walks through the whole thing: deploying it, locking it down, creating accounts, picking topics, setting up the phone apps, and connecting Butters so a notified event actually buzzes your pocket.
If you're still deciding between ntfy, web push and Slack, read Your phone as a pager, for free first.
What you need
- A Fly.io account and the
flyCLI, logged in withfly auth login. - A subdomain, like
ntfy.example.com, where you can add DNS records. (You can skip this and use the freeyour-app.fly.devaddress, but your own domain is easier to move later.) - The ntfy app on your phone, or a browser. We'll get to those.
One thing to settle before you start: your ntfy server needs a public address. Butters refuses to send to private and local addresses, so that a destination can't be used to poke around the network it runs in. On Fly, that means the public .fly.dev name or your own domain pointed at the app's public IPs. Fly's private network addresses, the .internal and .flycast names and the fdaa: IPv6 range, won't work as a Butters destination.
Step 1: Two files
Make an empty folder. Everything Fly needs fits in two files, plus one for ntfy's config.
First, server.yml. This is ntfy's own config file, and it's where we lock things down before the first boot:
base-url: "https://ntfy.example.com"
listen-http: ":8080"
cache-file: "/var/lib/ntfy/cache.db"
auth-file: "/var/lib/ntfy/user.db"
auth-default-access: "deny-all"
enable-signup: false
enable-login: true
behind-proxy: true
proxy-forwarded-header: "Fly-Client-IP"
upstream-base-url: "https://ntfy.sh" What each part does:
- `base-url` is the address your phone and Butters will use. Set it to your subdomain, or
https://your-app.fly.devif you're skipping the custom domain. - `cache-file` and `auth-file` both live in
/var/lib/ntfy, which is where we'll mount a volume. Without a volume, every deploy would wipe your accounts. - `deny-all` means nobody can read or publish unless you've given them access. Turning off signup means the only accounts are the ones you create. Leaving login on lets you sign in to the web app.
- `behind-proxy` tells ntfy it sits behind Fly's proxy, so it rate-limits by the real client IP instead of the proxy's. Fly puts that IP in the
Fly-Client-IPheader, so we point ntfy at it directly. - `upstream-base-url` is what makes the iOS app work. The phone section below explains why.
Next, a Dockerfile that puts that config where ntfy looks for it:
FROM binwiederhier/ntfy
COPY server.yml /etc/ntfy/server.yml
CMD ["serve"] Baking the config into /etc/ntfy/server.yml has a nice side effect: the ntfy command reads that file by default, so when you SSH in later to create users, it already knows where the database is. Swap binwiederhier/ntfy for a specific version tag from Docker Hub if you'd rather upgrade on purpose than on every deploy.
Finally, fly.toml:
app = "ntfy-yourname"
primary_region = "ord"
[http_service]
internal_port = 8080
force_https = true
auto_stop_machines = "off"
auto_start_machines = true
min_machines_running = 1
[[http_service.checks]]
method = "GET"
path = "/v1/health"
interval = "30s"
timeout = "5s"
grace_period = "10s"
[mounts]
source = "ntfy_data"
destination = "/var/lib/ntfy"
[[vm]]
size = "shared-cpu-1x"
memory = "256mb" Pick an app name that's free and a region near you. Two settings here matter more than they look.
`auto_stop_machines = "off"`. By default, Fly stops machines that look idle and starts them again on the next request. That's great for a website and wrong for a pager. A stopped machine has to boot before it can answer, and Butters only waits five seconds for ntfy to reply. Keeping the one machine running costs a little and means the first alert after a quiet night arrives like any other.
The `[mounts]` section attaches a volume, and a volume belongs to exactly one machine. That's fine, because ntfy keeps everything in SQLite files and should only ever run as one copy. Don't scale this app past one machine.
Step 2: Create the app and the volume
From the folder with those files:
fly apps create ntfy-yourname
fly volumes create ntfy_data --region ord --size 1 Use the same name and region as in fly.toml. One gigabyte is plenty. ntfy only keeps recent messages in its cache, and the user database is tiny.
Now deploy:
fly deploy --ha=false The --ha=false flag matters on the first deploy. Without it, Fly tries to create two machines for redundancy, and the second one would need its own volume with its own, separate copy of your users. One machine, one volume.
When it's up, open https://ntfy-yourname.fly.dev/v1/health in a browser. You should see {"healthy":true}.
Step 3: Point your domain at it
Skip this step if you're using the .fly.dev address.
Ask Fly for a certificate:
fly certs add ntfy.example.com It prints the DNS records to add. The simplest option is a CNAME from ntfy to ntfy-yourname.fly.dev. If your DNS provider doesn't allow a CNAME there, run fly ips list and add an A record for the IPv4 address and an AAAA record for the IPv6 one. The shared IPv4 address Fly gives every app is public, so Butters is happy with it.
Check progress with fly certs show ntfy.example.com. Once it says the certificate is issued, https://ntfy.example.com/v1/health should answer too. If you changed your mind about the domain after step 1, update base-url in server.yml and run fly deploy again.
Step 4: Create your accounts
You need two accounts: one for you, and one for Butters. Keeping them separate means you can revoke Butters without locking yourself out.
Open a shell on the machine:
fly ssh console Create yourself as an admin. Admins can read and write every topic, so you won't need any extra rules:
ntfy user add --role=admin roger It asks for a password twice. Then create a regular user for Butters:
ntfy user add butters That account can't do anything yet, because the default is deny-all. We'll give it access once we've picked topic names.
If ntfy user complains that it can't find the auth file, the config didn't make it into the image. Check that server.yml sits next to the Dockerfile and redeploy.
Step 5: Pick topics and grant access
There's no "create topic" step in ntfy. A topic exists as soon as someone publishes to it or subscribes to it. What you do control is who's allowed to touch it.
A prefix keeps this tidy. Put everything Butters sends under butters-, for example butters-prod for things that should wake you up and butters-daily for things that can wait. Then, still in the SSH session, give the Butters account write-only access to that prefix:
ntfy access butters 'butters-*' write-only Write-only is the right level here. Butters only publishes, so there's no reason for its credential to be able to read your topics back. The quotes stop the shell from expanding the *.
Check the result with:
ntfy access You should see your admin account with read-write on everything, butters with write-only on butters-*, and no access for anyone else.
Step 6: Make a token for Butters
Butters can log in with a username and password, but an access token is better. You can revoke it without changing a password, and it has a label so you know what it's for later.
ntfy token add --label="Butters" butters It prints a token that starts with tk_. Copy it somewhere safe for a minute. You'll paste it into Butters in step 8. Then type exit to leave the SSH session.
One thing to know: an ntfy token currently carries all of its user's permissions. That's another reason to give Butters its own write-only account instead of a token on your admin account.
Step 7: Set up your phone
The ntfy app is free on both platforms. Get it from Google Play or F-Droid on Android, or the App Store on iPhone.
The setup is the same on both:
- Open the app's settings and add a user for your server:
https://ntfy.example.com, with your admin username and password. The app then signs in to that server automatically. - Tap + to subscribe to a topic. Turn on the option to use another server, enter
https://ntfy.example.com, and type the topic name, likebutters-prod. - Repeat for each topic you want on this phone.
You can also set your server as the default in the app's settings, so you don't have to type it every time.
The two platforms deliver messages differently, and it's worth knowing how.
On Android, the app holds an open connection to your server. For self-hosted servers this happens even in the Google Play version, since that version only uses Google's push service for ntfy.sh. You'll see a permanent "subscription service" notification, which is what keeps the connection alive. You can hide it in Android's notification settings for the app. Android also gives each ntfy priority its own notification channel, so you can give priority 5 a sound that gets through Do Not Disturb and leave the rest quiet.
On iPhone, apps can't keep a connection open in the background, so iOS needs Apple's push service. That's what upstream-base-url is for. When a message arrives, your server sends a small poll request to ntfy.sh that contains only the message ID and a hash of the topic URL. ntfy.sh passes that to Apple, your phone wakes up, and it fetches the actual message from your server. The contents of your alerts never go through ntfy.sh. Without that setting, notifications on iOS still arrive, but they can be hours late.
If you'd rather not install anything, the web app at https://ntfy.example.com works too. Log in, subscribe to the same topics, and allow browser notifications.
Step 8: Connect Butters
In Butters, open your project's Settings, find the ntfy section, and click Add. Fill in the form:
- Friendly Name: anything, like "Phone, prod". It's only shown in the list.
- ntfy Topic:
butters-prod. Letters, digits, dashes and underscores, up to 64 characters. - Server URL:
https://ntfy.example.com. If you paste the full topic URL, Butters keeps just the origin, so that's fine too. - Priority: 1 to 5. Use 5 for anything that should wake you up.
- Authentication Method: Access token, then paste the
tk_token from step 6. - Icon URL: optional. A PNG or JPEG URL that ntfy shows as the notification icon.
Save it with Add destination, then click Test on the new row. Your phone should buzz within a second or two. If it doesn't, the row shows the error, and the next section explains the common ones.
Now send a real event with notify set. With the CLI :
butters push \
--project $PROJECT \
--category deploys \
--title "Deploy failed" \
--description "**api** on main, build step" \
--icon "🚨" \
--notify Or with curl:
curl -X POST https://app.getbutters.com/api/events \
-H "Authorization: Bearer $BUTTERS_KEY" \
-H "Content-Type: application/json" \
-d '{"project":"'$PROJECT'","category":"deploys","title":"Deploy failed","notify":true}' The notification's title is the event title, and the body is the description, with bold and links rendered. The category shows as a tag, and if the event has a link, tapping the notification opens it. Events without notify stay in the feed and never reach ntfy. Get pinged for the right events, and only those has a rule of thumb for when to set it.
A nice bonus if you deploy to Fly already: a fly deploy step in CI can send that same butters push when it fails, and the alert lands on a server running on the same platform.
When the test fails
Butters shows the last error on each destination, and most of them point straight at the problem.
- 403 Forbidden. The server was reached but the account isn't allowed to write to that topic. Check that the topic matches the prefix you granted in step 5, and run
ntfy accessagain overfly ssh console. - 401 Unauthorized. The token is wrong or was removed. Run
ntfy token list buttersto see what's there, and make a new one if needed. - Server redirected. You entered
http://, andforce_httpsredirected it tohttps://. Butters won't follow redirects on a publish, so use thehttps://URL. - Server URL points at a private or local address. You used a
.internalor.flycastname, or a privatefdaa:address. Use the.fly.devname or your own domain. - No response within 5s. Butters waits five seconds, then gives up on that event. Run
fly statusto check the machine is started, andfly logsto see why it isn't. If it shows as stopped, check thatauto_stop_machinesis"off"infly.tomland redeploy. - 429 Too Many Requests. ntfy's rate limits are per visitor, and every notification Butters sends comes from the same place. ntfy doesn't set a daily message limit unless you add one, so if you see this, look for a
visitor-message-daily-limitorvisitor-request-limit-*line inserver.ymland raise it.
If Test says it sent but nothing appears, the problem is on the phone. Check that you're subscribed to exactly the same topic on the same server, and on iPhone, check that upstream-base-url is still in server.yml.
Worth doing afterwards
Know where your backups are. Your accounts, tokens and access rules live in user.db on the volume. Fly takes daily snapshots of volumes and keeps them for a few days, and fly volumes list followed by fly volumes snapshots list <volume-id> shows them. Losing the cache only loses recent history. Losing the user database means doing steps 4 to 6 again, so if you want something longer-lived, copy user.db off the machine now and then with fly ssh sftp get /var/lib/ntfy/user.db.
Remember that Butters sends each event once. If your ntfy server is down when an event comes in, that notification is missed. It's still in the feed, and the error shows on the destination, but there's no retry. A single Fly machine restarts quickly, but it does restart, for deploys and for host maintenance. If an alert really matters, pair ntfy with web push or a Slack channel so one blip doesn't hide it.
Keep the Butters account small. If you add more senders later, like a backup script or a home server, give each one its own user, prefix and token. When one gets compromised or retired, you revoke one token and nothing else changes.
That's the whole setup: three small files, one volume, two accounts, one rule, one token. Your alerts now go from Butters to a server you control and straight to your phone, without a box of your own to look after.