Push Notifications on Your Own Terms
Most notification services route your alerts through someone else’s servers, subject to their uptime, their pricing tiers, and their data policies. Gotify removes that dependency entirely – it is a lightweight, open-source notification server you run yourself, giving you a direct channel between your apps, scripts, and devices without any third-party relay in the middle.
What Gotify Actually Does and Why It Matters
Gotify operates on a simple model: a server receives messages via a REST API, and connected clients display them in real time over WebSockets. You deploy the server on hardware you control, create application tokens for anything that needs to send notifications, and then receive those alerts on the Gotify Android app, the web interface, or any custom client that speaks WebSocket. There are no quotas, no monthly fees, and no rate limits imposed by a vendor.
The practical uses are wide. A home server running backup jobs can push a success or failure message the moment a task finishes. A Sonarr or Jellyfin setup can fire alerts when a new episode downloads. A cron job monitoring disk usage can warn you before a drive fills. Shell scripts, Python automations, and monitoring tools like Uptime Kuma all support Gotify natively or through a simple HTTP call. Once the server is running, plugging in a new notification source takes about sixty seconds.
Gotify is written in Go, which keeps the binary small and the memory footprint low. On a Raspberry Pi 4 with several active clients and dozens of daily messages, it typically uses under 30MB of RAM. That frugality makes it a natural fit for home servers that are already doing multiple jobs – a NAS, a media server, or a general-purpose VPS where resources matter.
The project stores messages in a SQLite database by default. This means you get a persistent log of every notification that came through, searchable through the web UI, without needing to configure a separate database engine. For high-volume scenarios there is experimental support for other backends, but for most self-hosters SQLite is more than adequate and eliminates one more moving part to maintain.
Installing and Configuring Gotify Step by Step
The fastest path to a working Gotify server is Docker. Pull the official image with docker pull gotify/server, then run it with a volume mount for persistent data and the port exposed on your local network. A minimal command looks like this:
docker run -d –name gotify -p 80:80 -v /opt/gotify/data:/app/data gotify/server
That single command starts the server, creates the data directory, and exposes the web interface on port 80. Navigate to the server’s IP in your browser and you will be greeted with a login prompt. The default credentials are admin and admin – change the password immediately from the Users panel before doing anything else. If you prefer Docker Compose, the official documentation provides a ready-made compose file that also adds environment variable support for configuring the default admin password before first boot, which is the cleaner option for a production-style setup.
Once logged in, create your first application from the Apps tab. Give it a descriptive name – something like “Home Server Scripts” or “Uptime Monitor” – and Gotify generates a token. That token is what your sending applications will use. To test it immediately, open a terminal and run a curl command: curl “http://your-server-ip/message?token=YOUR_TOKEN” -F “title=Test” -F “message=Gotify is working” -F “priority=5”. If the notification appears in the web UI within a second or two, the server is functioning correctly.
For production use, put Gotify behind a reverse proxy with TLS. Nginx and Caddy both work well. The key requirement is that the reverse proxy must support WebSocket proxying, because that is how real-time push to clients works. In Nginx, add proxy_http_version 1.1; along with the standard Upgrade and Connection headers to the location block. Caddy handles WebSocket proxying automatically with no extra directives. Without proper WebSocket support, clients will connect but messages will only appear after a manual page refresh – a common gotcha that trips up first-time installers.
The Android app is available on F-Droid as well as the Play Store. After installing it, tap the server icon, enter your Gotify server URL with the full https:// prefix, log in with your credentials, and the app registers for push. Android’s battery optimization will aggressively kill background connections on some devices, so add the Gotify app to the battery optimization whitelist from system settings. On iOS, there is no official client with native push because Apple’s push infrastructure requires an Apple developer account and a relay server – a deliberate limitation of the platform that Gotify’s architecture cannot work around without a third-party bridge like the ntfy.sh-style approach.
Sending Notifications From Scripts and Services
Because Gotify’s send API is just an HTTP POST with a form body, anything that can make an HTTP request can send a notification. In Python, the requests library handles it in three lines. In bash, curl works without any dependencies. Home Assistant has a built-in Gotify integration under its notification platform list, requiring only the server URL and token in the configuration. Node-RED has community nodes for Gotify. For monitoring stacks, Grafana supports Gotify as a contact point natively in its alerting system, and Prometheus Alertmanager can reach it through a webhook receiver pointed at the API endpoint.
Priority levels in Gotify run from 1 to 10. The Android client uses these to determine whether a notification makes a sound, vibrates silently, or appears only in the notification shade. Setting priority 1 for routine informational messages and priority 8 or higher for genuine alerts makes it possible to live with a high-volume notification setup without alert fatigue numbing you to the messages that actually need attention. That tuning, done at the sending script level rather than in a vendor dashboard, is one of the concrete advantages of owning the full notification stack.
