Posted inHomeLab

Stop Relying on the Cloud: Self-Host Gotify for Instant HomeLab Alerts

HomeLab tutorial - IT technology blog
HomeLab tutorial - IT technology blog

The 2 AM Realization: Why You Need a Local Notification Hub

It was 2:14 AM on a Tuesday. I woke up to a freezing house because my smart thermostat automation had crashed. I grabbed my phone—nothing. No alerts from Home Assistant, no emails from my NAS, and zero Telegram notifications. My ISP had started ‘scheduled maintenance’ at midnight, cutting my connection. Since my alerts relied on cloud-based APIs, they were essentially screaming into a digital void while my pipes risked freezing.

This is the classic HomeLab trap. We build complex local systems but outsource the most critical part—knowing when things break—to external services. That night, I realized I needed a notification server that lived where my data lived. I needed Gotify.

Think of Gotify as a private, high-speed message broker for your servers. It’s incredibly lightweight, typically sipping less than 30MB of RAM. It offers a clean web interface, a robust Android app, and a dead-simple API. If you can spin up a Docker container, you can have a private notification system running in under five minutes.

Quick Start: Gotify in 300 Seconds

I value simplicity over complex configurations. This minimal Docker Compose setup is all you need to get off the ground. First, create a home for your data.

mkdir -p ~/homelab/gotify/data
cd ~/homelab/gotify

Next, drop this configuration into a docker-compose.yml file. I’ve used this exact setup on a Raspberry Pi 4 for over 14 months without a single crash.

version: "3"

services:
  gotify:
    image: gotify/server
    container_name: gotify
    restart: always
    ports:
      - 8080:80
    environment:
      - GOTIFY_DEFAULTUSER_PASS=admin
    volumes:
      - "./data:/app/data"

Deploy the container:

docker-compose up -d

Now, point your browser to http://your-server-ip:8080. Use admin/admin to log in. Please, change that password immediately. You now own your notification infrastructure.

Under the Hood: Real-Time Communication

Gotify isn’t just a basic dashboard. It uses WebSockets to push messages to your devices instantly. This bypasses the lag of email and the uncertainty of spam filters. When a drive fails, you know within milliseconds, not minutes.

Creating Your First Application

In Gotify, an “Application” acts as your API key. You don’t send messages to “Gotify”; you send them to a specific App you’ve created. This allows you to categorize your alerts. I usually create separate Apps for:

  • Infrastructure: UPS status, disk space warnings, temperature alerts.
  • Security: Failed SSH attempts, firewall blocks.
  • Services: Docker container restarts, backup completion status.

Go to the Apps tab in the Gotify UI, click Create Application, give it a name like “HomeLab-Monitor”, and copy the Token. You’ll need this for the next step.

The Android Client

The Android app (available on F-Droid and Play Store) is where Gotify shines. It maintains a persistent WebSocket connection, meaning it doesn’t need Google’s Firebase Cloud Messaging (FCM) or a Google account to function. It just works—even if your internet is down but your local Wi-Fi is still up. For those with a custom Android build or a non-Google device, this is a lifesaver.

Practical Usage: Making Everything Talk

Once the server is running, the fun part begins: making everything talk to it. Since Gotify uses a simple REST API, you can send notifications from almost anything that can run a shell command or a script.

1. The Bash Script Method

I use this for my cron jobs. If a backup fails, I want to know immediately. Here is a simple curl command to send a high-priority notification:

curl -X POST "http://your-server-ip:8080/message?token=YOUR_APP_TOKEN" \
     -F "title=Backup Failed" \
     -F "message=The nightly backup of /mnt/data failed at $(date)" \
     -F "priority=8"

The priority field is key. In the Android app, you can configure different notification sounds based on priority. Priority 10 might trigger a loud alarm for a fire sensor, while priority 1 is a silent notification for a successful update.

2. Python Integration

If you’re writing custom automation scripts, Python makes it even easier. I often use this to monitor long-running data processing tasks.

import requests

def send_gotify_alert(title, message, priority=5):
    url = "http://192.168.1.50:8080/message?token=AmXyZ12345"
    payload = {
        "title": title,
        "message": message,
        "priority": priority
    }
    try:
        requests.post(url, json=payload)
    except Exception as e:
        print(f"Failed to send alert: {e}")

send_gotify_alert("Server Room Hot", "Temperature exceeded 30°C!", 9)

3. Reverse Proxy and SSL

If you want notifications while you’re away from home, you’ll need to expose Gotify to the internet. Do not just open port 8080 on your router. Use a reverse proxy like Nginx Proxy Manager or Caddy to handle SSL encryption. Gotify needs a secure connection (HTTPS) for WebSockets to work reliably over the public internet.

Practical Tips for a Noise-Free HomeLab

When I first set up Gotify, I made the mistake of sending a notification for everything. Every time a container updated, my phone buzzed. Within 48 hours, I was suffering from “alert fatigue” and started ignoring my phone. Don’t do that. It defeats the purpose of an alert system.

Tip 1: Use Priority Levels Wisely

Define a strict priority scale for your lab:

  • 0-3 (Low): Informational. No sound, no vibration. Useful for checking logs later.
  • 4-7 (Medium): Normal alerts. Standard notification sound. Use for things that need attention today, but not right now.
  • 8-10 (High): Critical. Unique loud sound, bypasses ‘Do Not Disturb’ if possible. Use for hardware failure or security breaches.

Tip 2: Use Markdown

Gotify supports Markdown in the message body. You can include links to your Portainer instance or Dashy dashboard directly in the notification. If a container fails, include a link to its logs in the message. It saves precious seconds when you’re trying to fix a problem on the go.

Tip 3: Healthcheck the Notifier

Who notifies you if the notification server goes down? I use a simple “heartbeat” script on a separate Raspberry Pi that pings Gotify every hour. If it fails, the Pi sends a fallback email or lights up a physical LED in my office. In a production-grade HomeLab, redundancy isn’t paranoia; it’s a requirement.

Setting up Gotify was one of the best stability upgrades I made to my stack. No more missed alerts, no more reliance on external APIs, and total control over my data. If you’re tired of wondering if your systems are actually running, spend the 20 minutes to set this up today.

Share:
Tags: