Stop Relying on Paid Alerts: Deploy Gotify for Instant Phone Notifications

When something breaks in your home lab, how long does it take you to find out? If you are like most people who run servers at home, you only notice when a family member texts you that Plex is down, your Nextcloud files stop syncing, or you log into Proxmox days later and realize a backup job has been silently failing.

For a long time, the standard fix was either signing up for commercial push services like Pushover or Twilio, or hacking together an email notification chain through an SMTP relay. But paid notification services add yet another subscription or per-message fee to your plate, and email alerts get lost in your spam folder or buried under marketing junk.

That is where Gotify comes in. Gotify is a completely free, open-source, self-hosted notification server written in Go. It uses minimal system resources, has a clean web UI, supports an official Android app, and lets you push real-time alerts straight to your phone with a single line of curl.

In this guide, we will walk through deploying Gotify with Docker Compose, testing it with a quick terminal script, and hooking it into Proxmox and your custom scripts so you always know the second a service hiccups.

Why Gotify Beats Traditional Alerting in a Home Lab

Before we fire up Docker, here is why Gotify has become a staple in modern self-hosted stacks:

• Zero Ongoing Costs: No monthly fee, no credit system, and no arbitrary limits on how many messages you can push.
• Insanely Lightweight: Written in Go, Gotify runs comfortably on 30 MB of RAM. You can spin it up on an old mini PC, a Raspberry Pi, or inside an unprivileged LXC container without noticing any resource drain.
• Direct WebSockets: It does not rely on third-party cloud brokers to deliver messages. The Android app maintains a persistent WebSocket connection directly to your server, giving you sub-second delivery.
• Clean API: Anything that can send an HTTP POST request can trigger a notification. That means shell scripts, Python scripts, Home Assistant, Uptime Kuma, and Proxmox can all talk to it natively.
• Priority System: You can assign priority numbers (0 to 10) to every alert. Low-priority messages silently update in your notification drawer, while high-priority emergency alerts vibrate and sound alarms.

Deploying Gotify with Docker Compose

The cleanest way to get Gotify running is through Docker Compose. Create a new directory for your Gotify project on your server:

mkdir -p ~/gotify && cd ~/gotify

Create a file named docker-compose.yml in that directory and paste in the following configuration:

services:
  gotify:
    image: gotify/server
    container_name: gotify
    restart: unless-stopped
    ports:
      - "8080:80"
    environment:
      - GOTIFY_DEFAULTUSER_PASS=ChangeThisPassword123
      - TZ=America/New_York
    volumes:
      - ./gotify_data:/app/data

Understanding the Configuration:

• image: gotify/server: Pulls the official, stable Gotify container image.
• ports: 8080:80: Maps internal port 80 to port 8080 on your host machine. If you already have another service running on 8080, change the left number (for example, 8085:80).
• GOTIFY_DEFAULTUSER_PASS: Sets the default password for the built-in admin user on first boot. Make sure to change this to a strong, unique password before running the container.
• TZ=America/New_York: Sets your local time zone so your timestamps align properly in message logs.
• volumes: ./gotify_data:/app/data: Binds a local folder on your host to persist Gotify’s SQLite database, uploaded icons, and message history. This ensures your data survives container updates.

Once you have saved your file, spin up the container in detached mode:

docker compose up -d

To verify that Gotify is running, run docker ps. You should see the gotify container in a healthy running state.

First Login and Generating an Application Token

Open your web browser and navigate to your server's local IP address on port 8080 (for example, http://192.168.1.50:8080).

Log in using the default credentials:

• Username: admin
• Password: The password you specified in GOTIFY_DEFAULTUSER_PASS

Once logged in, your first stop is the Apps tab in the top navigation bar. In Gotify terminology, an "App" is a sender. You will create a separate App for each service that sends alerts (for example, one for Proxmox, one for Backup Scripts, and one for Uptime Kuma).

1. Click Create Application.
2. Give it a descriptive name, such as Homelab Backups.
3. Click Create.
4. Gotify will generate a secret App Token (a string starting with A). Copy this key and save it somewhere safe—you will need it for your scripts.

Testing Your First Alert with curl

To prove how simple Gotify is to work with, open any terminal on your local network (or on the server itself) and run this test command:

curl "http://YOUR-SERVER-IP:8080/message" \
  -H "X-Gotify-Key: YOUR_APP_KEY_HERE" \
  -F "title=Server Alert" \
  -F "message=System backup completed without errors!" \
  -F "priority=0"

Replace YOUR-SERVER-IP:8080 with your Gotify instance address, and replace YOUR_APP_KEY_HERE with the token you just copied from the web UI.

As soon as you hit Enter, you will receive a JSON confirmation response in your terminal, and the new message will pop up instantly on your Gotify dashboard.

How Priority Levels Work in Gotify

Notice the -F "priority=0" flag in our test script. Gotify uses this number to determine how the receiving client should react:

• Priority 0 to 3 (Low): Subtle background notifications. Great for routine automated tasks like daily backups completing, disk scrub confirmations, or container health checks.
• Priority 4 to 7 (Normal): Standard mobile push notification with sound. Ideal for non-critical warnings, like high memory usage or a service restarting automatically.
• Priority 8 to 10 (High / Critical): Triggers maximum alert sound, vibration, and locks onto your lock screen. Perfect for power outages on your UPS, disk failures, or total server crashes.

Setting Up the Gotify Mobile App

Getting alerts on your desktop dashboard is helpful, but the real power of Gotify is receiving push notifications on your phone while you are away from your desk.

1. Download the official Gotify client from Google Play Store or F-Droid.
2. Open the app and enter your server URL (for example, https://gotify.yourdomain.com or your internal IP if connected over WireGuard / Tailscale).
3. Log in with your admin credentials (or create a standard client user in Gotify).
4. Give the client a recognizable name, like Pixel 8.
5. Under your phone's Android settings, make sure to disable battery optimization for Gotify. This prevents Android from putting the background WebSocket connection to sleep.

Note for iOS Users: While the official Gotify project focuses on Android, iOS users can easily receive Gotify notifications using lightweight compatible client apps like Forwarder or bridging Gotify Webhooks to Apple-compatible push tools.

Integrating Gotify with Proxmox VE

One of the best uses for Gotify in a home lab is monitoring your Proxmox hypervisor. Starting in Proxmox VE 8.1, Proxmox introduced a revamped notification system that natively supports Gotify without requiring any custom wrapper scripts!

Step-by-Step Proxmox Setup:

1. In the Proxmox web interface, click on Datacenter in the left tree.
2. Navigate to Notifications → Notification Targets.
3. Click Add and select Gotify from the dropdown.
4. Fill out the configuration fields:
   • Name: gotify-alerts
   • Server: http://192.168.1.50:8080 (or your HTTPS reverse proxy domain)
   • Token: The Application Token you created specifically for Proxmox.
5. Click Test. If configured correctly, your phone and Gotify web dashboard will immediately receive a test ping from Proxmox!
6. Click Add to save the target.

Now you can edit your Notification Matchers in Proxmox to route backup failure alerts, package upgrade notifications, and replication errors directly to your Gotify target. You will never have to wonder if last night's VM snapshot completed successfully.

Automating Custom Bash Script Alerts

You can embed Gotify notifications inside any custom backup or maintenance script using simple shell functions. Here is a practical example of wrapping a backup script:

#!/bin/bash

GOTIFY_URL="http://192.168.1.50:8080"
GOTIFY_TOKEN="Axxxxxxxxxxxxxx"

send_alert() {
  local TITLE="$1"
  local MESSAGE="$2"
  local PRIORITY="$3"

  curl -s -X POST "$GOTIFY_URL/message" \
    -H "X-Gotify-Key: $GOTIFY_TOKEN" \
    -F "title=$TITLE" \
    -F "message=$MESSAGE" \
    -F "priority=$PRIORITY" > /dev/null
}

# Example task
echo "Starting database backup..."
if tar -czf /backups/data_$(date +%F).tar.gz /var/lib/data; then
  send_alert "Backup Success" "Daily data backup finished cleanly." 2
else
  send_alert "BACKUP FAILED" "Critical: Daily backup failed to write to disk!" 9
fi

Security and Remote Access Best Practices

If you want notifications delivered to your phone when you are away from your home Wi-Fi network, you have two primary choices:

• Cloudflare Zero Trust Tunnel: Create a private tunnel pointing to port 8080. It gives you automatic SSL/TLS without forwarding any router ports. (Check out our Cloudflare Zero Trust guide on the blog for full steps).
• VPN (Tailscale / WireGuard): If you prefer not to expose Gotify to public DNS at all, keep Gotify on your internal subnet and keep your phone connected via an always-on WireGuard or Tailscale tunnel.

If you are running Gotify behind Nginx Proxy Manager, Caddy, or Traefik, ensure that your reverse proxy passes WebSocket upgrade headers (Upgrade $http_upgrade and Connection "upgrade"), otherwise real-time phone pushes may disconnect when the screen is locked.

Wrapping Up

Gotify solves one of the most frustrating parts of homelabbing: knowing when things go wrong before they cause real headaches. With a single, lightweight Docker container, you get private, instant phone alerts without subscriptions or third-party email hops.

Deploy it on your server today, link your Proxmox node, and sleep a little easier knowing your home lab has a voice.